IBM Cloud API Docs

Introduction

Last updated: 2024-10-22

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.

Most major frameworks are supported because App ID is based on OIDC. For help getting started in specific languages, see the tutorials for Python, Node.js, and Go.

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 Authorization 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

You might use one of two authentication methods when you interact with this API. If one of the following options is not used, the API is unprotected and does not require authorization. For more information and help obtaining your credentials and an access token, see obtaining tokens.

Basic authentication

A client ID and secret can be found in the Service Credentials or Applications tab of the App ID dashboard. Example: Authorization basic base64({client ID}:{secret})

App ID access token

When users or backend services interact with your app, they might need to be authorized to perform specific actions. App ID verifies that the entity that makes the request is authorized and returns access an access token to your app.

Security scheme

Authentication to this API's methods uses one of the following security schemes.

App_ID_Access_Token

Use the App ID access token of the user to authenticate, in the following format "Bearer <access_token>".

Attribute

Value
  • Type
    API Key
  • In
    Header
  • Name
    Authorization

Client_ID_and_Secret_Basic_Auth

Use the client ID and secret to authenticate (can be obtained from the service credentials tab in App ID console).

Attribute

Value
  • Type
    HTTP
  • Scheme
    Basic

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 to 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.

Related APIs

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

Still working with V3 endpoints? See the deprecated API.

Methods

User Info Preflight

Send a preflight request to retrieve user information.

OPTIONS /oauth/v4/{tenantId}/userinfo

Authentication

This method uses the Client_ID_and_Secret_Basic_Auth security scheme for authentication.

Request

Path Parameters

  • tenantId
    Required*
    string

    The service tenant ID or app GUID. The tenant ID can be found in the service credentials. You can create a service credential if one does not already exist.

  • curl -X 'OPTIONS'\'https://{region}.appid.cloud.ibm.com/oauth/v4/{tenant_ID}/userinfo'   -H 'accept: application/json'

Response

Response Body

string

Status Code

  • 204

    The request was successful.

No Sample Response

This method does not specify any sample responses.

Retrieve user information

Obtain additional user information from the identity provider which was used to authenticate the user. Learn more.

POST /oauth/v4/{tenantId}/userinfo

Authentication

This method uses the App_ID_Access_Token security scheme for authentication.

Request

Path Parameters

  • tenantId
    Required*
    string

    The service tenant ID or app GUID. The tenant ID can be found in the service credentials. You can create a service credential if one does not already exist.

  • curl -X 'POST' \'https://{region}.appid.cloud.ibm.com/oauth/v4/{tenant_ID}/userinfo'   -H 'accept: application/json'   -H 'Authorization: Bearer {acess_token}'   -d ''

Response

Response Body

user-info-response-v4

Status Code

  • 200

    The user information for the authenticated user is returned as a JSON object.

  • 400

    The request is incorrect.

  • 401

    The access token is expired, revoked, or malformed.

  • 403

    The scope is insufficient.

  • 500

    Returned in case of internal server error.

No Sample Response

This method does not specify any sample responses.

Retrieve user information

Obtain additional user information from the identity provider which was used to authenticate the user. Learn more.

GET /oauth/v4/{tenantId}/userinfo

Authentication

This method uses the App_ID_Access_Token security scheme for authentication.

Request

Path Parameters

  • tenantId
    Required*
    string

    The service tenant ID or app GUID. The tenant ID can be found in the service credentials. You can create a service credential if one does not already exist.

  • curl -X 'GET' \'https://{region}.appid.cloud.ibm.com/oauth/v4/{tenant_ID}/userinfo'   -H 'accept: application/json'   -H 'Authorization: Bearer {acess_token}'

Response

Response Body

user-info-response-v4

Status Code

  • 200

    The user information for the authenticated user is returned as a JSON object.

  • 400

    The request is incorrect.

  • 401

    The access token is expired, revoked, or malformed.

  • 403

    The scope is insufficient.

  • 500

    Returned in case of internal server error.

No Sample Response

This method does not specify any sample responses.

Log user activity

Log user activity in Activity Tracker. Learn more.

POST /oauth/v4/{tenantId}/activity_logging

Authentication

This method uses the App_ID_Access_Token security scheme for authentication.

Request

Custom Headers

  • Content-Type
    string

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

Path Parameters

  • tenantId
    Required*
    string

    The service tenant ID or app GUID. The tenant ID can be found in the service credentials. You can create a service credential if one does not already exist.

Request Body

Required*
object

The type of logged activity and the user's ID token are specified as a JSON object.

  • curl -X 'POST'\'https://{region}.appid.cloud.ibm.com/oauth/v4/{tenant_ID}/activity_logging'   -H 'accept: application/json'   -H 'Authorization: Bearer {access_token}'   -H 'Content-Type: application/json'   -d '{
"eventName": "logout",
"id_token": "id_token"
}'

Response

Status Code

  • 204

    The activity was logged.

  • 400

    The request is incorrect.

  • 401

    The access token is expired, revoked, or malformed.

  • 403

    The scope is insufficient.

No Sample Response

This method does not specify any sample responses.

Register client

Register clients on the App ID instance.

POST /oauth/v4/{tenantId}/clients

Request

Path Parameters

  • tenantId
    Required*
    string

    The service tenant ID or app GUID. The tenant ID can be found in the service credentials. You can create a service credential if one does not already exist.

Form Parameters

  • CSR
    Required*
    string

    The CSR is attached to the client registration request.

Response
Response Body
string
Status Code
  • 200
    The request was successful.
    

No Sample Response
This method does not specify any sample responses.
Authorization
Request App ID authorization. The method will follow one of the flows as set in the response_type field in the query parameters. Learn more.


GET /oauth/v4/{tenantId}/authorization
Request
Path Parameters
  • tenantId
    Required*
    string
    The service tenant ID or app GUID. The tenant ID can be found in the service credentials. You can create a service credential if one does not already exist.
    

Query Parameters
  • response_type
    Required*
    string
    The OAuth2 response type.
    

    Allowable values: [code,sign_up,forgot_password,change_details,change_password]
  • client_id
    Required*
    string
    The OAuth2 client ID that can be obtained from the service credentials.
    

  • redirect_uri
    Required*
    string
    The OAuth2 callback URI that is used for oauth-flows application. The URI will be invoked after successful authentication/authorization, or after the user clicks the login button.
    

  • scope
    Required*
    string
    The OAuth2 scope. The scope should be set to openid.
    

  • state
    string
    The OAuth2 state. The parameter should be set to a random string which you will be able to validate in subsequent steps.
    

  • idp
    string
    The identity provider name. An enabled IdP name or appid_anon for anonymous login. If left empty, the App ID Login Widget is returned with all enabled IdPs.
    

    Allowable values: [appid_anon,facebook,google,saml]
  • nonce
    string
    Optional parameter. If included, the nonce will be returned in the ID token to allow detection of ID token replay attacks by third parties.
    

  • appid_access_token
    string
    Optional parameter. The parameter supplies the previously obtained access token that is used to identify anonymous users.
    

  • user_id
    string
    The Cloud Directory user ID. The user ID is only required when the response-type is change_password.
    

  • code
    string
    The random code that is retrieved from the "/generate_code" endpoint. The code is only required when the response-type is change_details.
    

  • language
    string
    The Client language in the format as described in RFC5646.
    

  • code_challenge
    string
    The code_challenge parameter is required only for the PKCE flow.
    

  • code_challenge_method
    string
    The code_challenge_method parameter is required only for the PKCE flow.
    

  • curl -X 'GET' \'https://{region}.appid.cloud.ibm.com/oauth/v4/{tenant_ID}/authorization?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&scope=openid'   -H 'accept: application/json'
Response
Status Code
  • 200
    If you choose "sign_up" as the response_type, the LoginWidget sign up html form will be retrieved.
    

  • 302
    'The user is not authenticated yet or did not grant access permissions. The response will redirect the user to an authorization UI. Upon successful authentication, an HTTP redirect will be returned with the grant code and state query parameters, e.g. http://myApp.com/oauth/callback?code=ABCD&state=1234.
    

    The grant code should be used with the Token endpoint to obtain access and identity tokens. The state parameter equals to the state parameter supplied in the Authorization Endpoint request and can be used as an additional security layer.
    

    In case authentication fails or the user was denied access request one of the below error codes will be returned as error and state query parameters to the callback, e.g. http://myapp.com/oauth/callback?error=invalid_request&state=1234.
    

    Possible error codes are invalid_request, invalid_client, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable.'
    

  • 400
    The redirection URI is missing, invalid or mismatching, or the client indentifier is missing or invalid.
    

  • 500
    Returned in case of internal server error.
    

No Sample Response
This method does not specify any sample responses.
Token preflight
Send a preflight request to retrieve App ID tokens.


OPTIONS /oauth/v4/{tenantId}/token
Request
Path Parameters
  • tenantId
    Required*
    string
    The service tenant ID or app GUID. The tenant ID can be found in the service credentials. You can create a service credential if one does not already exist.
    

  • curl -X 'OPTIONS' \'https://{region}.appid.cloud.ibm.com/oauth/v4/{tenant_ID}/token'   -H 'accept: application/json'
Response
Response Body
string
Status Code
  • 204
    The request was successful.
    

No Sample Response
This method does not specify any sample responses.
Token
Retrieve App ID tokens. Learn more.


POST /oauth/v4/{tenantId}/token
Authentication
This method uses the Client_ID_and_Secret_Basic_Auth security scheme for authentication.
Request
Path Parameters
  • tenantId
    Required*
    string
    The service tenant ID or app GUID. The tenant ID can be found in the service credentials. You can create a service credential if one does not already exist.
    

Query Parameters
  • nonce
    string
    Optional parameter. If included, the nonce will be returned in the ID token to allow detection of ID token replay attacks by third parties.
    

Form Parameters
  • grant_type
    Required*
    string
    The OAuth2 grant type.
    

    Allowable values: [authorization_code,client_credentials,password,refresh_token,urn:ietf:params:oauth:grant-type:jwt-bearer]
  • redirect_uri
    string
    The OAuth2 callback URI that is used for oauth-flows application. The URI will be invoked after successful authentication/authorization. This parameter is required when the grant_type is authorization_code.
    

  • code
    string
    The OAuth2 grant code. The parameter is required when the grant_type is authorization_code.
    

  • username
    string
    The resource owner's username. If grant_type is selected, this parameter is required as well as the password.
    

  • password
    password
    The resource owner's password. If grant_type is selected, this parameter is required as well as the username.
    

  • scope
    string
    The list contains the different scopes requested by the client. The scopes within the list are separated by whitespace. The scope parameter is relevant only for the grant_type urn:ietf:params:oauth:grant-type:jwt-bearer and password flows.
    

  • appid_access_token
    string
    Optional parameter. The parameter supplies the previously obtained access token that is used to identify anonymous users. The parameter is relevant only when the grant_type is password.
    

  • refresh_token
    string
    The parameter is to issue a new access token when a valid refresh token is in use. It is required when the grant_type is refresh_token.
    

  • assertion
    string
    The IdP payload JWS is required when the grant flow is b>urn:ietf:params:oauth:grant-type:jwt-bearer. The payload, at a minimum, must contain the sub, exp, aud, and iss fields and be signed using the App ID Custom Flow private key.
    

  • code_verifier
    string
    The code_verifier parameter is required only for the PKCE flow.
    

  • audience
    string
    Optional parameter. The audience parameter is relevant only when the grant_type is client_credentials. Enter the Client ID of the audience application. Only scopes defined for the audience application will be included in the generated token. If audience is not specified, the client ID used to authorize the request will be used.
    

  • curl -X 'POST' \'https://{region}.appid.cloud.ibm.com/oauth/v4/{tenant_ID}/token'   -H 'accept: application/json'   -H 'authorization: Basic {base64Encoded{{client-ID}:{client-secret}}}'   -H 'Content-Type: application/x-www-form-urlencoded'   -d 'grant_type=<enter_grant_type>&redirect_uri=<enter_redirect_uri>&username=jdoe@example.com&password=password123'
Response
Response Body
token-endpoint-response-v3
Status Code
  • 200
    The method returns access and ID tokens, optional refresh token, and expiration information.
    

  • 400
    Parameters are missing, invalid or mismatching.
    

  • 500
    Returned in case of internal server error.
    

No Sample Response
This method does not specify any sample responses.
Revoke refresh token
Revoke a user's refresh token. Learn more.


POST /oauth/v4/{tenantId}/revoke
Authentication
This method uses the Client_ID_and_Secret_Basic_Auth security scheme for authentication.
Request
Path Parameters
  • tenantId
    Required*
    string
    The service tenant ID or app GUID. The tenant ID can be found in the service credentials. You can create a service credential if one does not already exist.
    

Form Parameters
  • token
    Required*
    string
    The App ID refresh token.
    

  • token_type_hint
    string
    The refresh token hint.
    

    Allowable values: [refresh_token]
  • curl -X 'POST' \'https://{region}.appid.cloud.ibm.com/oauth/v4/{tenant_ID}/revoke'   -H 'accept: application/json'   -H 'authorization: Basic {base64Encoded{{client-ID}:{client-secret}}}'   -H 'Content-Type: application/x-www-form-urlencoded'   -d 'token=Bearer%20{refresh_token}&token_type_hint=refresh_token'
Response
Response Body
string
Status Code
  • 200
    The request was successful.
    

  • 400
    Parameters are missing, invalid or mismatching.
    

  • 401
    The client_id or client_secret is invalid.
    

  • 500
    Returned in case of internal server error.
    

Example responses
  • OK
  • invalid_client
Introspect tokens
Introspect and validate App ID tokens. Learn more.


POST /oauth/v4/{tenantId}/introspect
Authentication
This method uses the Client_ID_and_Secret_Basic_Auth security scheme for authentication.
Request
Path Parameters
  • tenantId
    Required*
    string
    The service tenant ID or app GUID. The tenant ID can be found in the service credentials. You can create a service credential if one does not already exist.
    

Form Parameters
  • token
    Required*
    string
    The App ID access token.
    

  • curl -X 'POST'\'https://{region}.appid.cloud.ibm.com/oauth/v4/{tenant_ID}/introspect'   -H 'accept: application/json'   -H 'authorization: Basic {base64Encoded{{client-ID}:{client-secret}}}'   -H 'Content-Type: application/x-www-form-urlencoded'   -d 'token=<access_token>'
Response
Response Body
introspection-response
Status Code
  • 200
    The method returns a JSON Object in case of a valid/expired token.
    

  • 400
    Parameters are missing, invalid or mismatching.
    

  • 401
    The client ID, secret, username, or password is invalid.
    

  • 500
    Returned in case of internal server error.
    

No Sample Response
This method does not specify any sample responses.
Public keys retrival
Obtain public keys array for token signature verification. Learn more.


GET /oauth/v4/{tenantId}/publickeys
Request
Path Parameters
  • tenantId
    Required*
    string
    The service tenant ID or app GUID. The tenant ID can be found in the service credentials. You can create a service credential if one does not already exist.
    

  • curl -X 'GET'\'https://{region}.appid.cloud.ibm.com}/oauth/v4/{tenant_ID}/publickeys'   -H 'accept: application/json'
Response
Status Code
  • 200
    The public keys are returned as a JSON object.
    

  • 400
    The tenant ID is missing or invalid.
    

  • 404
    The tenant ID is missing or invalid.
    

  • 500
    Returned in case of internal server error.
    

No Sample Response
This method does not specify any sample responses.
Public keys preflight
Send a preflight request to obtain public keys.


OPTIONS /oauth/v4/{tenantId}/publickeys
Request
Path Parameters
  • tenantId
    Required*
    string
    The service tenant ID or app GUID. The tenant ID can be found in the service credentials. You can create a service credential if one does not already exist.
    

  • curl -X 'OPTIONS'\'https://{region}.appid.cloud.ibm.com/oauth/v4/{tenant_ID}/publickeys'   -H 'accept: application/json'
Response
Status Code
  • 204
    The request was successful. The preflight response is returned.
    

No Sample Response
This method does not specify any sample responses.
Generate temporary code
Obtain a temporary code that should be supplied to the authorization endpoint when response-type is change_details. The code is valid for 15 seconds.


GET /oauth/v4/{tenantId}/cloud_directory/generate_code
Request
Custom Headers
  • Authorization
    Required*
    string
    The App ID tokens in the format "Bearer <access_token> <id_token>".
    

Path Parameters
  • tenantId
    Required*
    string
    The service tenant ID or app GUID. The tenant ID can be found in the service credentials. You can create a service credential if one does not already exist.
    

Response
Status Code
  • 200
    The temporary code that should be supplied to the authorization endpoint when response-type is change_details is returned. The code is valid for 15 seconds.
    

  • 400
    Parameters are missing or invalid.
    

  • 401
    The username or password is invalid.
    

  • 500
    Returned in case of internal server error.
    

No Sample Response
This method does not specify any sample responses.
Discovery
Get the discovery endpoint for the OpenID Connect (OIDC) document including supported configuration and endpoints. Learn more.


GET /oauth/v4/{tenantId}/.well-known/openid-configuration
Request
Path Parameters
  • tenantId
    Required*
    string
    The service tenant ID or app GUID. The tenant ID can be found in the service credentials. You can create a service credential if one does not already exist.
    

  • curl -X 'GET'\'https://{region}.appid.cloud.ibm.com/oauth/v4/{tenant_ID}/.well-known/openid-configuration'   -H 'accept: application/json'
Response
Status Code
  • 200
    The OIDC document is returned as a JSON object, including supported configuration and endpoints.
    

  • 400
    The tenant ID is missing or invalid.
    

  • 500
    Returned in case of internal server error.
    

No Sample Response
This method does not specify any sample responses.
Logout a current SSO session
End a current Cloud Directory Single sign-on (SSO) session by logging out a user. Note: This request requires an SSO cookie. This API should be invoked to log out a user by redirecting their browser to this endpoint. Invoking this request in Swagger will show no response if a 302 status would be returned. Learn more. To end all sessions for a user, use the management API.


GET /oauth/v4/{tenantId}/cloud_directory/sso/logout
Request
Path Parameters
  • tenantId
    Required*
    string
    The service tenant ID or app GUID. The tenant ID can be found in the service credentials. You can create a service credential if one does not already exist.
    

Query Parameters
  • client_id
    Required*
    string
    The OAuth2 client ID that can be obtained from the service credentials.
    

  • redirect_uri
    Required*
    string
    The SSO logout callback URI. It is invoked after a successful logout.
    

Response
Status Code
  • 302
    Upon successful logout an HTTP redirect will be returned. In case the logout fails, one of the error codes will be returned as error to the callback, e.g. http://myapp.com/oauth/logout-callback?flow=sso_logout&error=missing_sso_code.
Possible error codes are missing_sso_code, invalid_client, unauthorized_client, server_error, temporarily_unavailable.
    

  • 400
    Parameters are missing or invalid.
    

  • 500
    Returned in case of internal server error.
    

No Sample Response
This method does not specify any sample responses.
Introspect tokens preflight
Introspect and validate App ID tokens. Learn more.


OPTIONS /oauth/v4/{tenantId}/introspect
Request
Path Parameters
  • tenantId
    Required*
    string
    The service tenant ID or app GUID. The tenant ID can be found in the service credentials. You can create a service credential if one does not already exist.
    

Form Parameters
  • token
    Required*
    string
    The App ID access token.
    

Response
Response Body
string
Status Code
  • 204
    The request was successful.
    

No Sample Response
This method does not specify any sample responses.
id=curlclassName=tab-item-selected