IBM Cloud API Docs

Introduction

With IBM Cloud™ App ID, you can secure resources and add authentication, even when you don't have a lot of security experience. By requiring users to sign in to your app, you can store user data such as preferences or information from their public social profiles that you can use to customize each experience of your app.

Need some help getting started? Check out this video tutorial on working with the Management API.

Endpoint URLs

App ID supports region-specific endpoint URLs that you can use to interact with the service over public service endpoints. To make requests to the Management API, you supply the endpoint URL that corresponds with the location where your App ID service instance resides.

Endpoint URLs by location

  • Dallas: https://us-south.appid.cloud.ibm.com
  • Frankfurt: https://eu-de.appid.cloud.ibm.com
  • London: https://eu-gb.appid.cloud.ibm.com
  • Osaka: https://jp-osa.appid.cloud.ibm.com
  • Sao Paulo: https://br-sao.appid.cloud.ibm.com
  • Sydney: https://au-syd.appid.cloud.ibm.com
  • Tokyo: https://jp-tok.appid.cloud.ibm.com
  • Toronto: https://ca-tor.appid.cloud.ibm.com
  • Washington: https://us-east.appid.cloud.ibm.com

Base URL

https://{region}.appid.cloud.ibm.com

Authentication

This API uses token-based IBM Cloud® Identity and Access Management (IAM) authentication.

To work with the Management APIs, you need to provide a valid IAM token in each request to the service. You can generate an IAM token by first creating an IBM Cloud API key and then exchanging your API key for an IBM Cloud IAM token.

Don't have an API key? Try running ibmcloud iam oauth-tokens in the IBM Cloud Shell to quickly generate a personal access token.

To generate an access token from your API key, use the following cURL command.

curl -X POST \
  "https://iam.cloud.ibm.com/identity/token" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Accept: application/json' \
  --data-urlencode 'grant_type=urn:ibm:params:oauth:grant-type:apikey' \
  --data-urlencode 'apikey={api_key}'

Replace {api_key} with your IBM Cloud API key. To learn more, check out the IAM docs.

Example that uses IAM authentication

curl -X {request_method} "{base_url}/api/v1/{method_endpoint}" --header "Authorization: Bearer {IAM_token}"

Replace {IAM_token} with your IBM Cloud IAM access token.

Auditing

You can monitor API activity within your account by using the IBM Cloud Activity Tracker service. Whenever an API method is called, an event is generated that you can then track and audit from within Activity Tracker. The specific event type is listed for each individual method.

For more information about how to track App ID activity, see Auditing events for App ID.

Error handling

The App ID APIs use standard HTTP status codes to indicate whether a method completed successfully. HTTP response codes in the 2xx range indicate success. A response in the 4xx range is some sort of failure, and a response in the 5xx range usually indicates an internal system error.

Status code summary
Status code Description
200 OK Everything worked as expected.
201 OK Everything worked as expected. No content is returned.
400 Bad Request The request was unsuccessful, often due to a missing required parameter.
401 Unauthorized The parameters were valid but the request failed due insufficient permissions.
404 Not Found The requested resource doesn't exist.
409 Conflict The requested resource conflicts with an already existing resource.
410 Gone The requested resource was deleted and no longer exists.
429 Too Many Requests Too many requests hit the API too quickly.
500 Internal Server Error Something went wrong on App ID's end.

Don't see the API endpoint that you're looking for? Check out the other APIs for Authorization and authentication and Profiles.

Methods

Get Facebook IDP configuration

Returns the Facebook identity provider configuration.

GET /management/v4/{tenantId}/config/idps/facebook

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.idps

Auditing

Calling this method generates the following auditing event.

  • appid.idp-config.read

Request

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Response

Status Code

  • Returns a JSON object of the Facebook identity provider configuration, including the status and credentials. Learn more.

  • The tenantId or request body is missing or invalid.

  • The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

  • The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

  • Returned in case of internal server error.

Example responses
  • {
      "isActive": true,
      "config": {
        "idpId": "facebook_appID",
        "secret": "facebook_appsecret"
      },
      "redirectURL": "https://us-south.appid.cloud.ibm.com/oauth/v4/39a37f57-a227-4bfe-a044-93b6e6060b61/Facebook/callback"
    }

Update Facebook IDP configuration

Configure Facebook to set up a single sign-on experience for your users. By using Facebook, users are able to sign in with credentials with which they are already familiar. Learn more.

PUT /management/v4/{tenantId}/config/idps/facebook

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.set.idps

Auditing

Calling this method generates the following auditing event.

  • appid.idp-config.update

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

The identity provider configuration as a JSON object. If the configuration is not set, IBM default credentials are used.

Response

Status Code

  • The Facebook configuration was updated. Returns a JSON object of the idp data.

  • The tenantId or request body is missing or invalid.

  • The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

  • The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

  • Returned in case of internal server error.

Example responses
  • {
      "isActive": true,
      "config": {
        "idpId": "facebook_appID",
        "secret": "facebook_appsecret"
      }
    }

Get Google IDP configuration

Returns the Google identity provider configuration.

GET /management/v4/{tenantId}/config/idps/google

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.idps

Auditing

Calling this method generates the following auditing event.

  • appid.idp-config.read

Request

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Response

Status Code

  • Returns a JSON object of the Google identity provider configuration, including the status and credentials. Learn more.

  • The tenantId or request body is missing or invalid.

  • The user is unauthorized. To be authorized a user needs an IAM token with the valid permissions.

  • The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

  • Returned in case of internal server error.

Example responses
  • {
      "isActive": true,
      "config": {
        "idpId": "google_appID",
        "secret": "google_appsecret"
      },
      "redirectURL": "https://us-south.appid.cloud.ibm.com/oauth/v4/39a37f57-a227-4bfe-a044-93b6e6060b61/Google/callback"
    }

Update Google IDP configuration

Configure Google to set up a single sign-on experience for your users. By using Google, users are able to sign in with credentials with which they are already familiar. Learn more.

PUT /management/v4/{tenantId}/config/idps/google

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.set.idps

Auditing

Calling this method generates the following auditing event.

  • appid.idp-config.update

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

The identity provider configuration as a JSON object. If the configuration is not set, IBM default credentials are used.

Response

Status Code

  • The Google configuration was updated. Returns a JSON object of the idp data.

  • The tenantId or request body is missing or invalid. The tenantId can be found in the service credentials.

  • The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

  • The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

  • Returned in case of internal server error.

Example responses
  • {
      "isActive": true,
      "config": {
        "idpId": "google_appID",
        "secret": "google_appsecret"
      }
    }

Get IBMid IDP configuration

Returns the IBMid identity provider configuration.

GET /management/v4/{tenantId}/config/idps/ibmid

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.idps

Auditing

Calling this method generates the following auditing event.

  • appid.idp-config.read

Request

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Response

Status Code

  • Returns a JSON object of the IBMid identity provider configuration, including the status and credentials.

  • The tenantId or request body is missing or invalid.