Introduction

Application security can be incredibly complicated. For most developers, it's one of the hardest part of creating an app. How can you be sure that you are protecting your users information? By integrating IBM® Cloud App ID into your apps, 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 app preferences or information from the public social profiles, and then use that data to customize each experience of your app. With this API, you can get started with authorization and authentication.

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.

Authentication

For the authentication and authorization APIs, there are three different types of authentication methods that might be used depending on the API:

  • Basic authentication using client ID and secret. The client ID and secret can be found in the Service Credentials tab of the App ID dashboard. Example: Authorization basic base64(<client ID>:<secret>)
  • App ID access token. Example: Authorization: Bearer <app id access token>
  • Unprotected.

Error handling

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

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

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.

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.
For more information, check out the docs.

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

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.

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
Request

Path Parameters

  • Service tenantId or appGuid

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

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.

registerClient

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

Path Parameters

  • Service tenantId or appGuid

Form Parameters

  • CSR attached to the client registration request

Response

Status Code

  • 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. For more information, check out the docs.

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

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

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.

No Sample Response

This method does not specify any sample responses.

Revoke refresh token

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

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

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

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.

No Sample Response

This method does not specify any sample 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

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

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

  • App ID tokens in the format, "Bearer "

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

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

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.

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

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.