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.

API endpoint

https://<region>.appid.cloud.ibm.com

Replace <region> with the prefix that represents the geographic area where your Key Protect service instance resides. For more informaton, see Managing App ID with the API.

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

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

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully.

HTTP Error Code Description Recovery
200 Success The request was successful.
400 Bad Request The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request.
401 Unauthorized You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact your account owner to check your permissions.
403 Forbidden The supplied authentication is not authorized.
404 Not Found The requested resource could not be found.
408 Request Timeout The connection to the server timed out. Wait a few minutes, then try again.
409 Conflict The entity is already in the requested state.
500 Internal Server Error App ID is currently unavailable. Your request could not be processed. Wait a few minutes and try again.

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

Retrieve User Info

Obtain additional user information from the identity provider which was used to authenticate the user.
For more information, check out the docs.

POST /oauth/v4/{tenantId}/userinfo
Request

Custom Headers

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

Path Parameters

  • Service tenantId or appGuid

Response

Status Code

  • Returns user information for the authenticated user.

  • Returned in case of a bad request.

  • Returned in case of expired, revoked, or malformed access token.

  • Returned in case of insufficient scope.

  • Returned in case of internal server error.

Example responses

Retrieve User Info

Obtain additional user information from the identity provider which was used to authenticate the user.
For more information, check out the docs.

GET /oauth/v4/{tenantId}/userinfo
Request

Custom Headers

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

Path Parameters

  • Service tenantId or appGuid

Response

Status Code

  • Returns user information for the authenticated user.

  • Returned in case of a bad request.

  • Returned in case of expired, revoked, or malformed access token.

  • Returned in case of insufficient scope.

  • Returned in case of internal server error.

Example responses

Log User Activity

Log user activity to Activity Tracker.

POST /oauth/v4/{tenantId}/activity_logging
Request

Custom Headers

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

Path Parameters

  • Service tenantId or appGuid

the type of logged activity and the user id_token, specified as a JSON object.

Example:
Response

Status Code

  • The activity was logged.

  • Returned in case of a bad request.

  • Returned in case of expired, revoked, or malformed access token.

  • Returned in case of insufficient scope.

No Sample Response

This method does not specify any sample responses.

Register a client

POST /oauth/v4/{tenantId}/clients
Request

Custom Headers

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

Path Parameters

  • Service tenantId or appGuid

Form Parameters

  • CSR attached to the client registration request

Response

Status Code

  • OK

Example responses

Authorization

Request App ID authorization. This will follow one of the flows as set in the response_type field. For more information, check out the docs.

GET /oauth/v4/{tenantId}/authorization
Request

Custom Headers

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

Path Parameters

  • Service tenantId or appGuid

Query Parameters

  • OAuth2 response type

    Allowable values: [code,sign_up,forgot_password,change_details,change_password]

  • OAuth2 client id as obtained from service credentials

  • OAuth2 callback uri for oauth-flows application. Will be invoked after successful authentication/authorization, or after the user clicks the login button

  • OAuth2 scope, should be set to openid

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

  • Identity provider name. Select an enabled IdP name or "appid_anon" for anonymous login. If left empty, App ID login widget will be returned with all enabled IdPs.

    Allowable values: [appid_anon,facebook,google,saml]

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

  • Optional parameter. Supplies previously obtained access token, used to identify anonymous users.

  • Cloud Directory user id, only require when response-type is change_password

  • Random code, retrieved from "/generate_code" endpoint, only required when response-type is change_details

  • Client language. Format as described in RFC5646

Response

Status Code

  • In case response_type equals "sign_up", the LoginWidget sign up html form will be retrieved.

  • In case user is not authenticated yet or did not grant access permissions previously the response will redirect user-agent to an authorization UI. Upon successful authentication an HTTP redirect will be returned with 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 user has 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.

  • Returned in case of missing, invalid or mismatching redirection URI, or if the client indentifier is missing or invalid.

  • Returned in case of internal server error.

No Sample Response

This method does not specify any sample responses.

Token

Return App ID tokens. For more information, check out the docs.

POST /oauth/v4/{tenantId}/token
Request

Custom Headers

Path Parameters

  • Service tenantId or appGuid

Query Parameters

  • 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

  • OAuth2 grant type

    Allowable values: [authorization_code,client_credentials,password,refresh_token,urn:ietf:params:oauth:grant-type:jwt-bearer]

  • OAuth2 callback uri for oauth-flows application. Will be invoked after successful authentication/authorization, on grant_type authorization_code flow this parameter is required

  • OAuth2 grant code, on grant_type authorization_code flow this parameter is required

  • The resource owner username, on grant_type password flow this parameter is required

  • The resource owner password, on grant_type password flow this parameter is required

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

  • Optional parameter. Supplies previously obtained access token, used to identify anonymous users. Relevant only for grant_type password flow

  • Used to issue a new access token when having a valid refresh token. Required for grant_type refresh_token.

  • The IdP payload JWS required by the urn:ietf:params:oauth:grant-type:jwt-bearer grant flow. 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.

Response

Status Code

  • Token endpoint response containing access and Id tokens, optional refresh token and also expiration information

  • Returned in case of missing, invalid or mismatching parameters.

  • Returned in case of internal server error.

Example responses

Revoke refresh token

Revoke a user's refresh token. For more information, check out the docs.

POST /oauth/v4/{tenantId}/revoke
Request

Custom Headers

Path Parameters

  • Service tenantId or appGuid

Form Parameters

  • App ID refresh token

  • refresh token hint

    Allowable values: [refresh_token]

Response

Status Code

  • Success response

  • Returned in case of missing, invalid or mismatching parameters

  • Returned in case of invalid client_id or client_secret.

  • Returned in case of internal server error.

Example responses

Introspect tokens

Introspect and validate App ID tokens. For more information, check out the docs.

POST /oauth/v4/{tenantId}/introspect
Request

Custom Headers

Path Parameters

  • Service tenantId or appGuid

Form Parameters

  • App ID token

Response

Status Code

  • Returns a JSON Object in case of a valid/expired token

  • Returned in case of missing, invalid or mismatching parameters

  • Returned in case of invalid client_id, invalid client_secret, invalid username or invalid password.

  • Returned in case of internal server error.

Example responses

Public keys retrival

Obtain public keys array for token signature verification. For more information, check out the docs.

GET /oauth/v4/{tenantId}/publickeys
Request

Custom Headers

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

Path Parameters

  • Service tenantId or appGuid

Response

Status Code

  • Returns json object of the public keys.

  • Returned in case of tenantId is missing or in case of invalid

  • Returned in case of tenantId is missing or in case of invalid

  • Returned in case of internal server error

Example 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

  • App ID tokens in the format, "Bearer "

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

Path Parameters

  • Service tenantId or appGuid

Response

Status Code

  • Returns temporary code that should be supplied to the authorization endpoint when response-type is change_details. The code is valid for 15 seconds.

  • Returned in case of missing or invalid parameters

  • Returned in case of invalid username or invalid password.

  • Returned in case of internal server error

No Sample Response

This method does not specify any sample responses.

Discovery

Discovery endpoint for OIDC document including supported configuration and endpoints.

GET /oauth/v4/{tenantId}/.well-known/openid-configuration
Request

Custom Headers

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

Path Parameters

  • Service tenantId or appGuid

Response

Status Code

  • Returns a JSON object with the OIDC document including supported configuration and endpoints.

  • Returned in case of missing or invalid tenantId

  • Returned in case of internal server error

Example responses

Logout a current SSO session

End a current Cloud Directory SSO session by logging out a user. Note: This request requires an SSO cookie.

GET /oauth/v4/{tenantId}/cloud_directory/sso/logout
Request

Custom Headers

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

Path Parameters

  • Service tenantId or appGuid

Query Parameters

  • OAuth2 client id as obtained from service credentials

  • The SSO logout callback URI. It is invoked after a successful logout

Response

Status Code

No Sample Response

This method does not specify any sample responses.