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.
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.
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 | 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
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
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
Log User Activity
Log user activity to Activity Tracker.
POST /oauth/v4/{tenantId}/activity_logging
Authentication
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
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
Required only for the PKCE flow.
Required only for the PKCE flow.
Response
Status Code
In case response_type equals "sign_up", the LoginWidget sign up html form will be retrieved.
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.
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
Token
Return App ID tokens. Learn more.
POST /oauth/v4/{tenantId}/token
Authentication
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.
Required only for the PKCE flow.
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
Example:
JALKjlzlkJLOI23enlLZJLCKnLKASd
Example:
KLAskd0aoskaojk3LKAJLkmxPIAS
Example:
eJYdAskd2dfskadjkeLKWwrQmxPIaKL
Example:
Bearer
Example:
3600
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
Revoke refresh token
Revoke a user's refresh token. Learn more.
POST /oauth/v4/{tenantId}/revoke
Authentication
Introspect tokens
Introspect and validate App ID tokens. Learn more.
POST /oauth/v4/{tenantId}/introspect
Authentication
Public keys retrival
Obtain public keys array for token signature verification. Learn more.
GET /oauth/v4/{tenantId}/publickeys
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
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
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
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.
Returned in case of missing or invalid parameters.
Returned in case of internal server error
No Sample Response
introspectPreflight
Introspect and validate App ID tokens. Learn more.
OPTIONS /oauth/v4/{tenantId}/introspect