IBM Cloud API Docs

Introduction

Last updated: 2021-05-17

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.

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

The App ID access token of the user, in the following format "Bearer <access_token>"

Attribute

Value
  • Type
    API Key
  • In
    Header
  • Name
    Authorization

Client ID and Secret Basic Auth

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

Attribute

Value
  • Type
    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 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

userinfoPreflight

OPTIONS /oauth/v4/{tenantId}/userinfo

Request

Path Parameters

  • tenantId
    Required*
    string

    Service tenantId or appGuid

Response

Response Body

string

Status Code

  • 204

    Returned in case of success.

No Sample Response

This method does not specify any sample responses.

Retrieve User Info

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

Custom Headers

  • Content-Type
    string

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

Path Parameters

  • tenantId
    Required*
    string

    Service tenantId or appGuid

Response

Response Body

user-info-response-v4

Status Code

  • 200

    Returns user information for the authenticated user.

  • 400

    Returned in case of a bad request.

  • 401

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

  • 403

    Returned in case of insufficient scope.

  • 500

    Returned in case of internal server error.

No Sample Response

This method does not specify any sample responses.

Retrieve User Info

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

    Service tenantId or appGuid

Response

Response Body

user-info-response-v4

Status Code

  • 200

    Returns user information for the authenticated user.

  • 400

    Returned in case of a bad request.

  • 401

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

  • 403

    Returned in case of insufficient scope.

  • 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 to Activity Tracker.

POST /oauth/v4/{tenantId}/activity_logging

Authentication

This method uses the App ID Access Token security scheme for authentication.

Auditing

Calling this method generates the following auditing event.

  • appid.user

Request

Custom Headers

  • Content-Type
    string

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

Path Parameters

  • tenantId
    Required*
    string

    Service tenantId or appGuid

Request Body

Required*
object

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

Response

Status Code

  • 204

    The activity was logged.

  • 400

    Returned in case of a bad request.

  • 401

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

  • 403

    Returned in case of insufficient scope.

No Sample Response

This method does not specify any sample responses.

registerClient

POST /oauth/v4/{tenantId}/clients

Request

Custom Headers

  • Content-Type
    string

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

Path Parameters

  • tenantId
    Required*
    string

    Service tenantId or appGuid

Form Parameters

  • CSR
    Required*
    string

    CSR attached to the client registration request

Response

Response Body

string

Status Code

  • 200

    OK

No Sample Response

This method does not specify any sample responses.

Authorization

Request App ID authorization. This will follow one of the flows as set in the response_type field. Learn more.

GET /oauth/v4/{tenantId}/authorization

Request

Path Parameters

  • tenantId
    Required*
    string

    Service tenantId or appGuid

Query Parameters

  • response_type
    Required*
    string

    OAuth2 response type

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

  • client_id
    Required*
    string

    OAuth2 client id as obtained from service credentials

  • redirect_uri
    Required*
    string

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

  • scope
    Required*
    string

    OAuth2 scope, should be set to openid

  • state
    string

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

  • idp
    string

    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]

  • 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. Supplies previously obtained access token, used to identify anonymous users.

  • user_id
    string

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

  • code
    string

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

  • language
    string

    Client language. Format as described in RFC5646

  • code_challenge
    string

    Required only for the PKCE flow.

  • code_challenge_method
    string

    Required only for the PKCE flow.

Response

Status Code

  • 200

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

  • 302

    In case the user is not yet authenticated 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, for example 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 has denied access request, one of the following error codes will be returned as error and state query parameters to the callback, for example http://myapp.com/oauth/callback?error=invalid_request&state=1234.

    Possible error codes include: invalid_request, invalid_client, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable.

  • 400

    Returned in case of missing, invalid or mismatching redirection URI, or if 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.

tokenPreflight

OPTIONS /oauth/v4/{tenantId}/token

Request

Path Parameters

  • tenantId
    Required*
    string

    Service tenantId or appGuid

Response

Response Body

string

Status Code

  • 204

    Returned in case of success.

No Sample Response

This method does not specify any sample responses.

Token

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

Auditing

Calling this method generates the following auditing events.

  • appid.application.authenticate

  • appid.user.authenticate

Request

Path Parameters

  • tenantId
    Required*
    string

    Service tenantId or appGuid

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

    OAuth2 grant type

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

  • redirect_uri
    string

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

  • code
    string

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

  • username
    string

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

  • password
    password

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

  • scope
    string

    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.

  • appid_access_token
    string

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

  • refresh_token
    string

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

  • assertion
    string

    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.

  • code_verifier
    string

    Required only for the PKCE flow.

  • audience
    string

    Optional parameter, relevant only with grant_type=client_credentials. clientId of audience application. Only scopes defined for the audience application will be included in the generated token. If audience is not specified, clientId used to authorize this request will be used.

Response

Response Body

token-endpoint-response-v3

Status Code

  • 200

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

  • 400

    Returned in case of missing, invalid or mismatching parameters.

  • 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

    Service tenantId or appGuid

Form Parameters

  • token
    Required*
    string

    App ID refresh token

  • token_type_hint
    string

    refresh token hint

    Allowable values: [refresh_token]

Response

Response Body

string

Status Code

  • 200

    Success response

  • 400

    Returned in case of missing, invalid or mismatching parameters

  • 401

    Returned in case of invalid client_id or client_secret.

  • 500

    Returned in case of internal server error.

  • x-ibm-events
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

    Service tenantId or appGuid

Form Parameters

  • token
    Required*
    string

    App ID token

Response

Response Body

introspection-response

Status Code

  • 200

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

  • 400

    Returned in case of missing, invalid or mismatching parameters

  • 401

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

  • 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

    Service tenantId or appGuid

Response

Status Code

  • 200

    Returns json object of the public keys.

  • 400

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

  • 404

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

  • 500

    Returned in case of internal server error

No Sample Response

This method does not specify any sample responses.

publicKeysPreflight

OPTIONS /oauth/v4/{tenantId}/publickeys

Request

Path Parameters

  • tenantId
    Required*
    string

    Service tenantId or appGuid

Response

Status Code

  • 204

    Returns preflight response.

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

    App ID tokens in the format, "Bearer "

Path Parameters

  • tenantId
    Required*
    string

    Service tenantId or appGuid

Response

Status Code

  • 200

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

  • 400

    Returned in case of missing or invalid parameters

  • 401

    Returned in case of invalid username or invalid password.

  • 500

    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

Path Parameters

  • tenantId
    Required*
    string

    Service tenantId or appGuid

Response

Status Code

  • 200

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

  • 400

    Returned in case of missing or invalid tenantId

  • 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 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. Learn more.

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

Auditing

Calling this method generates the following auditing event.

  • appid.cloud-dir-user-credentials.renew

Request

Path Parameters

  • tenantId
    Required*
    string

    Service tenantId or appGuid

Query Parameters

  • client_id
    Required*
    string

    OAuth2 client id as obtained from 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 logout fails, one of the following error codes will be returned as error to the callback, for example http://myapp.com/oauth/logout-callback?flow=sso_logout&error=missing_sso_code.

    Possible error codes include: missing_sso_code, invalid_client, unauthorized_client, server_error, temporarily_unavailable.

  • 400

    Returned in case of missing or invalid parameters.

  • 500

    Returned in case of internal server error

No Sample Response

This method does not specify any sample responses.

introspectPreflight

Introspect and validate App ID tokens. Learn more.

OPTIONS /oauth/v4/{tenantId}/introspect

Request

Path Parameters

  • tenantId
    Required*
    string

    Service tenantId or appGuid

Form Parameters

  • token
    Required*
    string

    App ID token

Response

Response Body

string

Status Code

  • 204

    Returned in case of success.

No Sample Response

This method does not specify any sample responses.