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.
You can more easily access the API from your code with the available SDKs for Android, iOS, Node.js, Swift, and Javascript. The client libraries that are provided by the SDKs implement best practices for using the API and reduce the amount of code that you need to write.
To learn more about using the SDKs, see the IBM Cloud SDK Common project on Github. For more information about getting started with App ID, check out the docs.
You can more easily access the API from your code with the available SDKs for Android, iOS, Node.js, Swift, and Javascript. The client libraries that are provided by the SDKs implement best practices for using the API and reduce the amount of code that you need to write.
To learn more about using the SDKs, see the IBM Cloud SDK Common project on Github. For more information about getting started with App ID, check out the docs.
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 Management 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
This API uses token-based IBM Cloud® Identity and Access Management (IAM) authentication.
To work with the Management APIs, you need to provide a valid IAM token in each request to the service. You can generate an IAM token by first creating an IBM Cloud API key and then exchanging your API key for an IBM Cloud IAM token.
Don't have an API key? Try running ibmcloud iam oauth-tokens in the IBM Cloud Shell to quickly generate a personal access token.
To generate an access token from your API key, use the following cURL command.
curl -X POST \
"https://iam.cloud.ibm.com/identity/token" \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--data-urlencode 'grant_type=urn:ibm:params:oauth:grant-type:apikey' \
--data-urlencode 'apikey={api_key}'
Replace {api_key} with your IBM Cloud API key. To learn more, check out the IAM docs.
Example that uses IAM authentication
curl -X {request_method} "{base_url}/api/v1/{method_endpoint}" --header "Authorization: Bearer {IAM_token}"
Replace {IAM_token} with your IBM Cloud IAM access token.
Auditing
You can monitor API activity within your account by using the IBM Cloud Logs service. Whenever an API method is called, an event is generated that you can then track and audit from within IBM Cloud Logs. The specific event type is listed for each individual method.
For more information about how to track App ID activity, see Activity tracking 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 Authorization and authentication and Profiles.
Methods
Get Facebook IDP configuration
Get the Facebook identity provider configuration. Learn more.
GET /management/v4/{tenantId}/config/idps/facebookRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
curl -X 'GET' \ 'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/idps/facebook' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}"'
Response
The status of the configuration.
The details of the configuration.
- config
The application ID. By default, Facebook is enabled as an identity provider by using IBM credentials. You can add your own credentials by creating an account on the Facebook Developers site{ :external} and obtaining a client ID and secret.
The application secret. By default, Facebook is enabled as an identity provider by using IBM credentials. You can add your own credentials by creating an account on the Facebook Developers site{ :external} and obtaining a client ID and secret.
Status Code
The Facebook identity provider configuration is returned as a JSON object, including the status and credentials. Learn more.
The tenant ID or request body is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
Returned because of an internal server error.
{ "isActive": true, "config": { "idpId": "facebook_appID", "secret": "facebook_appsecret" }, "redirectURL": "https://us-south.appid.cloud.ibm.com/oauth/v4/39a37f57-a227-4bfe-a044-93b6e6060b61/Facebook/callback" }
Update Facebook IDP configuration
Configure Facebook to set up a single sign-on experience for your users. By using Facebook, your users are able to sign in with credentials with which they are already familiar. Learn more.
PUT /management/v4/{tenantId}/config/idps/facebookRequest
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The identity provider configuration as a JSON object. If the configuration is not set, IBM default credentials are used.
The status of the configuration.
Example:
trueThe details of the configuration.
- config
The application ID.
Example:
appIDThe application secret.
Example:
appsecret
curl -X 'PUT' \'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/idps/facebook' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}' -H 'Content-Type: application/json' -d '{ "isActive": true, "config": { "idpId": "appID", "secret": "appsecret" }, "additionalProp1": {} }'
Response
The status of the configuration.
The details of the configuration.
- config
The application ID. By default, Facebook is enabled as an identity provider by using IBM credentials. You can add your own credentials by creating an account on the Facebook Developers site{ :external} and obtaining a client ID and secret.
The application secret. By default, Facebook is enabled as an identity provider by using IBM credentials. You can add your own credentials by creating an account on the Facebook Developers site{ :external} and obtaining a client ID and secret.
Status Code
The Facebook configuration was updated. The identity provider data is returned as a JSON object.
The tenant ID or request body is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
Returned due to an internal server error.
{ "isActive": true, "config": { "idpId": "facebook_appID", "secret": "facebook_appsecret" } }
Get Google IDP configuration
Get the Google identity provider configuration.
GET /management/v4/{tenantId}/config/idps/googleRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
curl -X 'GET' \ 'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/idps/google' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}"'
Response
The status of the configuration.
The details of the configuration.
- config
The client ID. By default, Google is enabled as an identity provider by using IBM credentials. You can add your own credentials by creating an account on the Google Developer Console{ :external} and obtaining a client ID and secret.
The client secret. By default, Google is enabled as an identity provider by using IBM credentials. You can add your own credentials by creating an account on the Google Developer Console{ :external} and obtaining a client ID and secret.
Status Code
The Google identity provider configuration is returned as a JSON object, including the status and credentials. Learn more.
The tenant ID or request body is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
Returned because of an internal server error.
{ "isActive": true, "config": { "idpId": "google_appID", "secret": "google_appsecret" }, "redirectURL": "https://us-south.appid.cloud.ibm.com/oauth/v4/3ghfjh7-a227-4bfe-a044-93bihjgjgh1/Google/callback" }
Update Google IDP configuration
Configure Google to set up a single sign-on experience for your users. By using Google, your users are able to sign in with credentials with which they are already familiar. Learn more.
PUT /management/v4/{tenantId}/config/idps/googleRequest
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The identity provider configuration as a JSON object. If the configuration is not set, IBM default credentials are used.
The status of the configuration.
Example:
trueThe details of the configuration.
- config
The application ID.
Example:
appIDThe application secret.
Example:
appsecret
curl -X 'PUT' \'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/idps/google' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}' -H 'Content-Type: application/json' -d '{ "isActive": true, "config": { "idpId": "appID", "secret": "appsecret" }, "additionalProp1": {} }'
Response
The status of the configuration.
The details of the configuration.
- config
The client ID. By default, Google is enabled as an identity provider by using IBM credentials. You can add your own credentials by creating an account on the Google Developer Console{ :external} and obtaining a client ID and secret.
The client secret. By default, Google is enabled as an identity provider by using IBM credentials. You can add your own credentials by creating an account on the Google Developer Console{ :external} and obtaining a client ID and secret.
Status Code
The Google configuration was updated. The identity provider data is returned as a JSON object.
The tenant ID or request body is missing or invalid. The tenant ID can be found in the service credentials.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
Returned due to an internal server error.
{ "isActive": true, "config": { "idpId": "google_appID", "secret": "google_appsecret" } }
Get IBMid IDP configuration
Get the IBMid identity provider configuration.
GET /management/v4/{tenantId}/config/idps/ibmidRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
curl -X 'GET' \'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/idps/ibmid' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
The status of the configuration.
Example:
trueThe details of the configuration.
- config
The IBMid client ID. You can find the IBMid client ID, secret, and phase can be found on the IBMid application registration page. For more details, see our documentation.
Example:
appIDThe IBMid client secret. You can find the IBMid client ID, secret, and phase can be found on the IBMid application registration page. For more details, see our documentation.
Example:
appsecretThe IBMid pre-production phase. You can find the IBMid client ID, secret and phase can be found on the IBMid application registration page. For more details, see our documentation.
Example:
trueThe IBMid production phase. You can find the IBMid client ID, secret and phase can be found on the IBMid application registration page. For more details, see our documentation.
Example:
true
Status Code
The IBMid identity provider configuration is returned as a JSON object, including the status and credentials.
The tenant ID or request body is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
Returned because of an internal server error.
No Sample Response
Update IBMid IDP configuration
Configure IBMid to set up a single sign-on experience for your users. Learn more.
PUT /management/v4/{tenantId}/config/idps/ibmidRequest
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The identity provider configuration as a JSON object. If the configuration is not set, IBM default credentials are used.
The status of the configuration.
Example:
trueThe details of the configuration.
- config
The IBMid client ID. You can find the IBMid client ID, secret, and phase can be found on the IBMid application registration page. For more details, see our documentation.
Example:
appIDThe IBMid client secret. You can find the IBMid client ID, secret, and phase can be found on the IBMid application registration page. For more details, see our documentation.
Example:
appsecretThe IBMid pre-production phase. You can find the IBMid client ID, secret and phase can be found on the IBMid application registration page. For more details, see our documentation.
Example:
trueThe IBMid production phase. You can find the IBMid client ID, secret and phase can be found on the IBMid application registration page. For more details, see our documentation.
Example:
true
curl -X 'PUT' \'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/idps/ibmid' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}' -H 'Content-Type: application/json' -d '{ "isActive": true, "config": { "idpId": "appID", "secret": "appsecret", "preProd": true, "ciBased": true }, "additionalProp1": {} }'
Response
The status of the configuration..
The redirect URL.
The details of the configuration.
- config
The IBMid client ID. You can find the IBMid client ID, secret, and phase can be found on the IBMid application registration page. For more details, see our documentation.
The IBMid client secret. You can find the IBMid client ID, secret, and phase can be found on the IBMid application registration page. For more details, see our documentation.
The IBMid pre-production phase. You can find the IBMid client ID, secret and phase can be found on the IBMid application registration page. For more details, see our documentation.
The IBMid production phase. You can find the IBMid client ID, secret and phase can be found on the IBMid application registration page. For more details, see our documentation.
Status Code
The IBMid configuration was updated. The identity provider data is returned as a JSON object.
The tenant ID or request body is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
Returned because of an internal server error.
{ "isActive": true, "config": { "idpId": "client_id", "secret": "client_secret", "preProd": false, "ciBased": true }, "redirectURL": "https://example.com" }
Get Custom identity configuration
Get the Custom identity configuration.
GET /management/v4/{tenantId}/config/idps/customRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
curl -X 'GET' \'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/idps/custom' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
The status of the configuration.
The details of the configuration.
- config
The public key.
Status Code
The Custom identity configuration is returned as a JSON object that contains the PEM public key and the isActive status.
The tenant ID or request body is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
Returned because of an internal server error.
{ "isActive": true, "config": { "publicKey": "-----BEGIN RSA PUBLIC KEY-----u0mGFYvwLArEZNrK5SBwd...vPeBHF3Kq2xDfvhTBsl79j-----END RSA PUBLIC KEY-----" } }
Update or change the configuration of the Custom identity.
Configure App ID Custom identity to allow users to sign in by using your own identity provider.
PUT /management/v4/{tenantId}/config/idps/customRequest
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The identity provider configuration as a JSON object.
{
"isActive": true,
"config": {
"publicKey": "-----BEGIN RSA PUBLIC KEY-----u0mGFYvwLArEZNrK5SBwd...vPeBHF3Kq2xDfvhTBsl79j-----END RSA PUBLIC KEY-----"
}
}The status of the configuration.
The details of the configuration.
- config
The public key.
curl -X 'PUT' \'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/idps/custom' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}' -H 'Content-Type: application/json' -d '{ "isActive": true, "config": { "publicKey": "[enter_rsa_public_key]" } }'
Response
The status of the configuration.
The details of the configuration.
- config
The public key.
Status Code
The Custom identity configuration was updated. The updated configuration is returned as a JSON object.
The tenant ID or request body is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
Returned because of an internal server error.
{ "isActive": true, "config": { "publicKey": "-----BEGIN RSA PUBLIC KEY-----u0mGFYvwLArEZNrK5SBwd...vPeBHF3Kq2xDfvhTBsl79j-----END RSA PUBLIC KEY-----" } }
Get Cloud Directory IDP configuration
Get the Cloud Directory identity provider configuration. Learn more.
GET /management/v4/{tenantId}/config/idps/cloud_directoryRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
curl -X 'GET' \'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/idps/cloud_directory' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
The status of the configuration.
Example:
trueThe details of the configuration.
- config
You allow your users to manage their account from your application.
Example:
trueThe interactions that you allow your users to have with your application.
- interactions
You ask your users to verify their identity (i.e, email address).
- identityConfirmation
The type of access that you allow your users to have.
Possible values: [
FULL,RESTRICTIVE,OFF]The method through which your users can verify their identity.
Possible values: [
email]
The welcome email that is used to welcome users to your application after they've signed up is enabled.
The forgot password email is enabled. You can use it to allow a user to request a reset of their password. A user must have validated their email prior to resetting their password.
The password changed email is enabled. You can use it to notify the user about changes to their password.
Example:
true
You allow your users to sgn-up to your application.
Example:
trueThe identity field.
Possible values: [
email,userName]
Status Code
The Cloud Directory identity provider configuration is returned as a JSON object, including the status and credentials.
The tenant ID or request body is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
Returned because of an internal server error.
{ "isActive": true, "config": { "selfServiceEnabled": true, "signupEnabled": true, "interactions": { "identityConfirmation": { "accessMode": "FULL", "methods": [ "email" ] }, "welcomeEnabled": false, "resetPasswordEnabled": false, "resetPasswordNotificationEnable": true }, "identityField": "email" } }
Update Cloud Directory IDP configuration
Configure Cloud Directory to set up a single sign-on experience for your users. With Cloud Directory, users can use their email and a password of their choice to log in to your applications. Learn more.
PUT /management/v4/{tenantId}/config/idps/cloud_directoryRequest
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The identity provider configuration as a JSON object. If the configuration is not set, IBM default credentials are used.
The status of the configuration.
Example:
true- config
You allow your users to manage their account from your application.
Example:
trueThe interactions that you allow your users to have with your application.
- interactions
You ask your users to verify their identity (i.e, email address).
- identityConfirmation
The type of access that you allow your users to have.
Allowable values: [
FULL,RESTRICTIVE,OFF]The method through which your users can verify their identity.
Allowable values: [
email]
The welcome email that is used to welcome users to your application after they've signed up is enabled.
The forgot password email is enabled. You can use it to allow a user to request a reset of their password. A user must have validated their email prior to resetting their password.
The password changed email is enabled. You can use it to notify the user about changes to their password.
Example:
true
You allow your users to sgn-up to your application.
Example:
trueThe identity field.
Allowable values: [
email,userName]
curl -X 'PUT'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/idps/cloud_directory' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}' -H 'Content-Type: application/json' -d '{ "isActive": true, "config": { "selfServiceEnabled": true, "signupEnabled": true, "interactions": { "identityConfirmation": { "accessMode": "FULL", "methods": [ "email" ] }, "welcomeEnabled": false, "resetPasswordEnabled": false, "resetPasswordNotificationEnable": true }, "identityField": "email" } }'
Response
The status of the configuration.
Example:
trueThe details of the configuration.
- config
You allow your users to manage their account from your application.
Example:
trueThe interactions that you allow your users to have with your application.
- interactions
You ask your users to verify their identity (i.e, email address).
- identityConfirmation
The type of access that you allow your users to have.
Possible values: [
FULL,RESTRICTIVE,OFF]The method through which your users can verify their identity.
Possible values: [
email]
The welcome email that is used to welcome users to your application after they've signed up is enabled.
The forgot password email is enabled. You can use it to allow a user to request a reset of their password. A user must have validated their email prior to resetting their password.
The password changed email is enabled. You can use it to notify the user about changes to their password.
Example:
true
You allow your users to sgn-up to your application.
Example:
trueThe identity field.
Possible values: [
email,userName]
Status Code
The Cloud Directory configuration was updated. The identity provider data is returned as a JSON object.
The tenant ID or request body is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
Returned because of an internal server error.
{ "isActive": true, "config": { "selfServiceEnabled": true, "signupEnabled": true, "interactions": { "identityConfirmation": { "accessMode": "FULL", "methods": [ "email" ] }, "welcomeEnabled": false, "resetPasswordEnabled": false, "resetPasswordNotificationEnable": true }, "identityField": "email" } }
Get SAML IDP configuration
Get the SAML identity provider configuration, including status and credentials. Learn more.
GET /management/v4/{tenantId}/config/idps/samlRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
curl -X 'GET'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/idps/saml' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
The status of the configuration.
The configuration of the SAML IDP.
Examples:{ "entityID": "https://example.com/saml2/metadata/706634", "signInUrl": "https://example.com/saml2/sso-redirect/706634", "certificates": [ "certificate-example-pem-format" ], "displayName": "my saml example", "authnContext": { "class": [ "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport" ], "comparison": "exact" }, "signRequest": false, "encryptResponse": false }
Status Code
The identity provider configuration for SAML is returned as a JSON object.
The tenant ID or request body is missing or invalid. The tenant ID can be found in the service credentials.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
Returned because of an internal server error.
{ "isActive": true, "config": { "entityID": "https://example.com/saml2/metadata/706634", "signInUrl": "https://example.com/saml2/sso-redirect/706634", "certificates": [ "certificate-example-pem-format" ], "displayName": "my saml example", "authnContext": { "class": [ "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport" ], "comparison": "exact" }, "signRequest": false, "encryptResponse": false } }
Update SAML IDP configuration
Configure SAML to set up a single sign-on experience for your users. Learn more.
PUT /management/v4/{tenantId}/config/idps/samlRequest
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The identity provider configuration as a JSON object.
The status of the configuration.
Example:
trueThe configuration of the SAML IDP.
Examples:{ "entityID": "https://example.com/saml2/metadata/706634", "signInUrl": "https://example.com/saml2/sso-redirect/706634", "certificates": [ "certificate-example-pem-format" ], "displayName": "my saml example", "authnContext": { "class": [ "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport" ], "comparison": "exact" }, "signRequest": false, "encryptResponse": false }- config
The entity ID.
The sign-in URL.
The certificates issued by your SAML identity provider. Certificates are used for signing and validating SAML assertions. Supply the certificate in PEM format.
The display name.
The authorization context.
- authnContext
The class.
Allowable values: [
urn:oasis:names:tc:SAML:2.0:ac:classes:InternetProtocol,urn:oasis:names:tc:SAML:2.0:ac:classes:InternetProtocolPassword,urn:oasis:names:tc:SAML:2.0:ac:classes:Kerberos,urn:oasis:names:tc:SAML:2.0:ac:classes:MobileOneFactorUnregistered,urn:oasis:names:tc:SAML:2.0:ac:classes:MobileTwoFactorUnregistered,urn:oasis:names:tc:SAML:2.0:ac:classes:MobileOneFactorContract,urn:oasis:names:tc:SAML:2.0:ac:classes:MobileTwoFactorContract,urn:oasis:names:tc:SAML:2.0:ac:classes:Password,urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport,urn:oasis:names:tc:SAML:2.0:ac:classes:PreviousSession,urn:oasis:names:tc:SAML:2.0:ac:classes:X509,urn:oasis:names:tc:SAML:2.0:ac:classes:PGP,urn:oasis:names:tc:SAML:2.0:ac:classes:SPKI,urn:oasis:names:tc:SAML:2.0:ac:classes:XMLDSig,urn:oasis:names:tc:SAML:2.0:ac:classes:Smartcard,urn:oasis:names:tc:SAML:2.0:ac:classes:SmartcardPKI,urn:oasis:names:tc:SAML:2.0:ac:classes:SoftwarePKI,urn:oasis:names:tc:SAML:2.0:ac:classes:Telephony,urn:oasis:names:tc:SAML:2.0:ac:classes:NomadTelephony,urn:oasis:names:tc:SAML:2.0:ac:classes:PersonalTelephony,urn:oasis:names:tc:SAML:2.0:ac:classes:AuthenticatedTelephony,urn:oasis:names:tc:SAML:2.0:ac:classes:SecureRemotePassword,urn:oasis:names:tc:SAML:2.0:ac:classes:TLSClient,urn:oasis:names:tc:SAML:2.0:ac:classes:TimeSyncToken,urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified]The comparison.
Allowable values: [
exact,maximum,minimum,better]
The sign request.
The encrypted response.
Scoping is included.
curl -X 'PUT' \'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/idps/saml' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}' -H 'Content-Type: application/json' -d '{ "isActive": true, "config": { "entityID": "https://example.com/saml2/metadata/706634", "signInUrl": "https://example.com/saml2/sso-redirect/706634", "certificates": [ "certificate-example-pem-format" ], "displayName": "my_saml_example", "authnContext": { "class": [ "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport" ], "comparison": "exact" }, "signRequest": false, "encryptResponse": false } }'
Response
The status of the configuration.
The configuration of the SAML IDP.
Examples:{ "entityID": "https://example.com/saml2/metadata/706634", "signInUrl": "https://example.com/saml2/sso-redirect/706634", "certificates": [ "certificate-example-pem-format" ], "displayName": "my saml example", "authnContext": { "class": [ "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport" ], "comparison": "exact" }, "signRequest": false, "encryptResponse": false }- validation_data
The certificates that are issued by your SAML identity provider. It is used for signing and validating SAML assertions. Supply the certificate in PEM format.
- certificates
The certificate index.
The expiration data.
The expiration warning.
Status Code
The SAML configuration was updated. The idp data is returned as a JSON object.
The tenant ID or request body is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
Returned because of an internal server error.
{ "isActive": true, "config": { "entityID": "https://example.com/saml2/metadata/706634", "signInUrl": "https://example.com/saml2/sso-redirect/706634", "certificates": [ "certificate-example-pem-format" ], "displayName": "my saml example", "authnContext": { "class": [ "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport" ], "comparison": "exact" }, "signRequest": false, "encryptResponse": false }, "validation_data": { "certificates": [ { "certificate_index": 0, "expiration_timestamp": 1674473996, "warning": "Your certificate will expire in 18 days." } ] } }
Get tokens configuration
Get the token configuration. Learn more.
GET /management/v4/{tenantId}/config/tokensRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
curl -X 'GET'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/tokens' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
The claims of the identity token.
- idTokenClaims
The source of the claim of the token.
Possible values: [
saml,cloud_directory,appid_custom,facebook,google,ibmid,attributes,roles]The source claim.
The destination claim.
Possible values: length ≤ 300
The claims of the access token.
- accessTokenClaims
The source of the claim of the token.
Possible values: [
saml,cloud_directory,appid_custom,facebook,google,ibmid,attributes,roles]The source claim.
The destination claim.
Possible values: length ≤ 300
The expiration data of the access token.
Examples:{ "expires_in": 3600 }The expiration and activity data of the refresh token.
Examples:{ "expires_in": 2592000, "enabled": true }The expiration and activity data of the anonymous token.
Examples:{ "expires_in": 2592000, "enabled": true }
Status Code
Returns a JSON object of the App ID tokens properties.
The tenant ID or request body is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
{ "idTokenClaims": [ { "source": "attributes", "sourceClaim": "theme" } ], "accessTokenClaims": [ { "source": "saml", "sourceClaim": "user_type", "destinationClaim": "type" } ], "access": { "expires_in": 3600 }, "refresh": { "expires_in": 2592000, "enabled": true }, "anonymousAccess": { "expires_in": 2592000, "enabled": true } }
Update tokens configuration
Update the tokens' configuration to fine-tune the expiration times of access, ID, and refresh tokens to enable or disable refresh and anonymous tokens, and to configure custom claims. When a token config object is not included in the set, its value is reset back to default. For more information, check out the key concepts.
PUT /management/v4/{tenantId}/config/tokensRequest
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
Set of App ID token objects. 'expires_in' is set in seconds.
{
"idTokenClaims": [
{
"source": "attributes",
"sourceClaim": "theme"
}
],
"accessTokenClaims": [
{
"source": "saml",
"sourceClaim": "user_type",
"destinationClaim": "type"
}
],
"access": {
"expires_in": 3600
},
"refresh": {
"expires_in": 2592000,
"enabled": true
},
"anonymousAccess": {
"expires_in": 2592000,
"enabled": true
}
}The claims of the identity token.
- idTokenClaims
The source of the claim of the token.
Allowable values: [
saml,cloud_directory,appid_custom,facebook,google,ibmid,attributes,roles]The source claim.
The destination claim.
Possible values: length ≤ 300
The claims of the access token.
- accessTokenClaims
The source of the claim of the token.
Allowable values: [
saml,cloud_directory,appid_custom,facebook,google,ibmid,attributes,roles]The source claim.
The destination claim.
Possible values: length ≤ 300
The expiration data of the access token.
Examples:{ "expires_in": 3600 }The expiration and activity data of the refresh token.
Examples:{ "expires_in": 2592000, "enabled": true }The expiration and activity data of the anonymous token.
Examples:{ "expires_in": 2592000, "enabled": true }
curl -X 'PUT'\'https://{region}.appid.cloud.ibm.com/management/v4/tenant_ID}/config/tokens' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}' -H 'Content-Type: application/json' -d '{ "idTokenClaims": [ { "source": "attributes", "sourceClaim": "theme" } ], "accessTokenClaims": [ { "source": "saml", "sourceClaim": "user_type", "destinationClaim": "type" } ], "access": { "expires_in": 3600 }, "refresh": { "expires_in": 2592000, "enabled": true }, "anonymousAccess": { "expires_in": 2592000, "enabled": true } }'
Response
The claims of the identity token.
- idTokenClaims
The source of the claim of the token.
Possible values: [
saml,cloud_directory,appid_custom,facebook,google,ibmid,attributes,roles]The source claim.
The destination claim.
Possible values: length ≤ 300
The claims of the access token.
- accessTokenClaims
The source of the claim of the token.
Possible values: [
saml,cloud_directory,appid_custom,facebook,google,ibmid,attributes,roles]The source claim.
The destination claim.
Possible values: length ≤ 300
The expiration data of the access token.
Examples:{ "expires_in": 3600 }The expiration and activity data of the refresh token.
Examples:{ "expires_in": 2592000, "enabled": true }The expiration and activity data of the anonymous token.
Examples:{ "expires_in": 2592000, "enabled": true }
Status Code
The token configuration was updated.
The tenant ID or request body is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
{ "idTokenClaims": [ { "source": "attributes", "sourceClaim": "theme" } ], "accessTokenClaims": [ { "source": "saml", "sourceClaim": "user_type", "destinationClaim": "type" } ], "access": { "expires_in": 3600 }, "refresh": { "expires_in": 2592000, "enabled": true }, "anonymousAccess": { "expires_in": 2592000, "enabled": true } }
Get redirect URIs
Get the list of the redirect URIs that can be used as callbacks of App ID authentication flow. Learn more.
GET /management/v4/{tenantId}/config/redirect_urisRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
curl -X 'GET'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/redirect_uris' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
The redirect URLs.
Status Code
An array of the redirect URIs is returned as a JSON object.
The tenant ID parameter is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
{ "redirectUris": [ "https://example.com/oauth-callback" ] }
Update redirect URIs
Update the list of the redirect URIs that can be used as callbacks of App ID authentication flow. Learn more.
PUT /management/v4/{tenantId}/config/redirect_urisRequest
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The redirect URIs JSON object. If IBM default credentials are used, the redirect URIs are ignored.
The redirect URLs.
The redirect URLs of trusted cloud IAM.
curl -X 'PUT'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/redirect_uris' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}' -H 'Content-Type: application/json' -d '{ "redirectUris": [ "http://localhost:3000/oauth-callback" ], "additionalProp1": {} }'
Response
Status Code
No content. The redirect URIs were updated.
The tenant ID or request body is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify permissions.
No Sample Response
Get user profiles configuration
Get the user profiles configuration. A user profile is an entity that is stored and maintained by App ID. The profile holds a user's attributes and identity. It can be anonymous or linked to an identity that is managed by an identity provider. Learn more.
GET /management/v4/{tenantId}/config/users_profileRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
curl -X 'GET'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/users_profile' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
The status of the configuration.
Status Code
The current profiles status is returned as a JSON object.
The tenant ID is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify permissions.
{ "isActive": false }
Update user profiles configuration
Update the user profiles configuration. A user profile is an entity that is stored and maintained by App ID. The profile holds a user's attributes and identity. It can be anonymous or linked to an identity that is managed by an identity provider.Learn more.
PUT /management/v4/{tenantId}/config/users_profileRequest
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The user profile data. It can be enabled or disabled.
The status of the configuration.
Example:
true
curl -X 'PUT'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/users_profile' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}' -H 'Content-Type: application/json' -d '{ "isActive": true }'
Response
Status Code
No content. The user profiles status was updated.
The tenant ID or request body is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify permissions.
No Sample Response
Get widget texts
Get the theme texts of the App ID login widget. Learn more.
GET /management/v4/{tenantId}/config/ui/theme_textRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
curl -X 'GET'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/ui/theme_text' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
The footnote.
The tab title.
Status Code
The current color configuration is returned as a JSON object.
The tenant ID is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify permissions.
{ "tabTitle": "Login", "footnote": "Powered by App ID" }
Update widget texts
Update the texts of the App ID login widget. Learn more.
PUT /management/v4/{tenantId}/config/ui/theme_textRequest
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The texts of the widget.
The tab title.
Possible values: length ≤ 100
Example:
LoginThe footnote.
Possible values: length ≤ 3000
Example:
Powered by App ID
curl -X 'PUT'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/ui/theme_text' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}" -H 'Content-Type: application/json' -d '{ "tabTitle": "Login api-test", "footnote": "Powered by App ID" }'
Response
Status Code
No content, the service login widget header color was updated.
The tenant ID or request body is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify permissions.
No Sample Response
Get widget colors
Get the colors of the App ID login widget. Learn more.
GET /management/v4/{tenantId}/config/ui/theme_colorRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
curl -X 'GET'\'{base_url}/management/v4/{tenant_ID}/config/ui/theme_color' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
The color of the header.
Status Code
The current color configuration is returned as a JSON object.
The tenant ID is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify permissions.
{ "headerColor": "#EEF2F5" }
Update widget colors
Update the colors of the App ID login widget. Learn more.
PUT /management/v4/{tenantId}/config/ui/theme_colorRequest
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The colors of the widget.
The color of the header.
Example:
#EEF2F5
curl -X 'PUT'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/ui/theme_color' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}" -H 'Content-Type: application/json' -d '{ "headerColor": "{#EEF2F5}" }'
Response
Status Code
No content, the service login widget header color was updated.
The tenant ID or request body is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify permissions.
No Sample Response
Delete widget logo
Delete the image file shown in the login widget. Learn more.
DELETE /management/v4/{tenantId}/config/ui/mediaRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
Query Parameters
The type of media. You can upload JPG or PNG files.
Allowable values: [
logo]
curl -X 'DELETE' \'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/ui/media?mediaType=logo' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}''
Get widget logo
Get the link to the custom logo image of the login widget. Learn more.
GET /management/v4/{tenantId}/config/ui/mediaRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
curl -X 'GET'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/ui/media' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}''
Response
The custom logo image of the login widget.
Status Code
The current media configurations are returned as a JSON object.
The tenant ID, file type, or file size are invalid or missing. The file must be either a JPG or PNG that is less than 100 kb.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify permissions.
{ "image": "image-url" }
Update widget logo
Update the image file shown in the login widget. Learn more.
POST /management/v4/{tenantId}/config/ui/mediaRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
Query Parameters
The type of media. You can upload JPG or PNG files.
Allowable values: [
logo]
Form Parameters
The image file. The recommended size is 320x320 px. The maximum files size is 100 kb.
curl -X 'POST'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/ui/media?mediaType=logo' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}" -H 'Content-Type: multipart/form-data' -F 'file=unsplash.jpg;type=image/jpeg'
Response
Status Code
No content. The service login widget logo was updated.
The tenant ID, file type, or file size are invalid or missing. The file must be either a JPG or PNG that is less than 100 kb.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify permissions.
No Sample Response
Get the SAML metadata
Get the SAML metadata that you need to integrate App ID with a SAML identity provider. Learn more.
GET /management/v4/{tenantId}/config/saml_metadataRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
curl -X 'GET' \'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/saml_metadata' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}''
Response
Status Code
The metadata for using SAML as a service provider is returned as an xml snippet.
The tenant ID parameter is missing or invalid.
Returned because of an internal server error.
<SPSSODescriptor WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"><NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat><AssertionConsumerService index="1" isDefault="true" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://us-south.appid.cloud.ibm.com/saml2/v1/login-acs"/></SPSSODescriptor>
Get an email template
Get the content of a custom email template or the default template in case it wasn't customized. Learn more.
GET /management/v4/{tenantId}/config/cloud_directory/templates/{templateName}/{language}Request
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The type of email template. The type can be "USER_VERIFICATION", "WELCOME", "PASSWORD_CHANGED", "RESET_PASSWORD" or "MFA_VERIFICATION".
Allowable values: [
USER_VERIFICATION,RESET_PASSWORD,WELCOME,PASSWORD_CHANGED,MFA_VERIFICATION]Preferred language for resource. Format as described at RFC5646. According to the configured languages codes returned from the
GET /management/v4/{tenantId}/config/ui/languagesAPI.
curl -X 'GET'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/cloud_directory/templates/{USER_VERIFICATION}/en' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
The subject of the email.
The HTML body of the email.
The HTML body of the email encoded in Base64.
The plain text body of the email.
Status Code
The email template data is returned as a JSON object. If the language template does not exist yet, the english template (en) is returned.
The tenant ID or templateName are missing or invalid or language is not in the app localization configuration.
The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify permissions.
{ "subject": "Verify your email for %{user.displayName}", "html_body": "<h3>Hello %{user.displayName}</h3>\\n<p>Follow this link to verify your email address</p>\\n<p><a href='%{verify.link}'>%{verify.link}</a></p>\\n<p>If you didn't ask to verify this address, you can ignore this email</p>\\n<p>Thanks,</p>\\n<p>Your BMLand team</p>", "base64_encoded_html_body": "PGgzPkhlbGxvICV7dXNlci5kaXNwbGF5TmFtZX08L2gzPlxuPHA+Rm9sbG93IHRoaXMgbGluayB0byB2ZXJpZnkgeW91ciBlbWFpbCBhZGRyZXNzPC9wPlxuPHA+PGEgaHJlZj0nJXt2ZXJpZnkubGlua30nPiV7dmVyaWZ5Lmxpbmt9PC9hPjwvcD5cbjxwPklmIHlvdSBkaWRuJ3QgYXNrIHRvIHZlcmlmeSB0aGlzIGFkZHJlc3MsIHlvdSBjYW4gaWdub3JlIHRoaXMgZW1haWw8L3A+XG48cD5UaGFua3MsPC9wPlxuPHA+WW91ciBCTUxhbmQgdGVhbTwvcD4=" }
Update an email template
Update the Cloud Directory email template. Learn more.
PUT /management/v4/{tenantId}/config/cloud_directory/templates/{templateName}/{language}Request
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The type of email template. The type can be "USER_VERIFICATION", "WELCOME", "PASSWORD_CHANGED", "RESET_PASSWORD" or "MFA_VERIFICATION".
Allowable values: [
USER_VERIFICATION,RESET_PASSWORD,WELCOME,PASSWORD_CHANGED,MFA_VERIFICATION]Preferred language for resource. Format as described at RFC5646. According to the configured languages codes returned from the
GET /management/v4/{tenantId}/config/ui/languagesAPI.
Email template object. See documentation for available placeholder for each email template.
{
"subject": "Verify Your email for %{user.displayName}",
"base64_encoded_html_body": "PGgzPkhlbGxvICV7dXNlci5kaXNwbGF5TmFtZX08L2gzPlxuPHA+Rm9sbG93IHRoaXMgbGluayB0byB2ZXJpZnkgeW91ciBlbWFpbCBhZGRyZXNzPC9wPlxuPHA+PGEgaHJlZj0nJXt2ZXJpZnkubGlua30nPiV7dmVyaWZ5Lmxpbmt9PC9hPjwvcD5cbjxwPklmIHlvdSBkaWRuJ3QgYXNrIHRvIHZlcmlmeSB0aGlzIGFkZHJlc3MsIHlvdSBjYW4gaWdub3JlIHRoaXMgZW1haWw8L3A+XG48cD5UaGFua3MsPC9wPlxuPHA+WW91ciBCTUxhbmQgdGVhbTwvcD4="
}The subject of the email.
The HTML body of the email.
The HTML body of the email encoded in Base64.
The plain text body of the email.
curl -X 'PUT'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/cloud_directory/templates/{USER_VERIFICATION}/en' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}" -H 'Content-Type: application/json' -d '{ "subject": "Verify Your Email for %{user.displayName}", "base64_encoded_html_body": "PGgzPkhlbGxvICV7dX" }'
Response
The subject of the email.
The HTML body of the email.
The HTML body of the email encoded in Base64.
The plain text body of the email.
Status Code
The email template properties are returned as a JSON object.
The created email template properties are returned as a JSON object.
No content. The template configuration was updated (in case the request Prefer header is return_minimal).
The tenant ID or request body is missing or invalid.
The user is unauthorized.
The user has insufficient permissions.
{ "subject": "Verify your email for %{user.displayName}", "html_body": "<h3>Hello %{user.displayName}</h3>\\n<p>Follow this link to verify your email address</p>\\n<p><a href='%{verify.link}'>%{verify.link}</a></p>\\n<p>If you didn't ask to verify this address, you can ignore this email</p>\\n<p>Thanks,</p>\\n<p>Your BMLand team</p>", "base64_encoded_html_body": "PGgzPkhlbGxvICV7dXNlci5kaXNwbGF5TmFtZX08L2gzPlxuPHA+Rm9sbG93IHRoaXMgbGluayB0byB2ZXJpZnkgeW91ciBlbWFpbCBhZGRyZXNzPC9wPlxuPHA+PGEgaHJlZj0nJXt2ZXJpZnkubGlua30nPiV7dmVyaWZ5Lmxpbmt9PC9hPjwvcD5cbjxwPklmIHlvdSBkaWRuJ3QgYXNrIHRvIHZlcmlmeSB0aGlzIGFkZHJlc3MsIHlvdSBjYW4gaWdub3JlIHRoaXMgZW1haWw8L3A+XG48cD5UaGFua3MsPC9wPlxuPHA+WW91ciBCTUxhbmQgdGVhbTwvcD4=" }{ "subject": "Verify your email for %{user.displayName}", "html_body": "<h3>Hello %{user.displayName}</h3>\\n<p>Follow this link to verify your email address</p>\\n<p><a href='%{verify.link}'>%{verify.link}</a></p>\\n<p>If you didn't ask to verify this address, you can ignore this email</p>\\n<p>Thanks,</p>\\n<p>Your BMLand team</p>", "base64_encoded_html_body": "PGgzPkhlbGxvICV7dXNlci5kaXNwbGF5TmFtZX08L2gzPlxuPHA+Rm9sbG93IHRoaXMgbGluayB0byB2ZXJpZnkgeW91ciBlbWFpbCBhZGRyZXNzPC9wPlxuPHA+PGEgaHJlZj0nJXt2ZXJpZnkubGlua30nPiV7dmVyaWZ5Lmxpbmt9PC9hPjwvcD5cbjxwPklmIHlvdSBkaWRuJ3QgYXNrIHRvIHZlcmlmeSB0aGlzIGFkZHJlc3MsIHlvdSBjYW4gaWdub3JlIHRoaXMgZW1haWw8L3A+XG48cD5UaGFua3MsPC9wPlxuPHA+WW91ciBCTUxhbmQgdGVhbTwvcD4=" }
Delete an email template
Delete the customized email template and reverts to App ID default template. Learn more.
DELETE /management/v4/{tenantId}/config/cloud_directory/templates/{templateName}/{language}Request
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The type of email template. The type can be "USER_VERIFICATION", "WELCOME", "PASSWORD_CHANGED", "RESET_PASSWORD" or "MFA_VERIFICATION".
Allowable values: [
USER_VERIFICATION,RESET_PASSWORD,WELCOME,PASSWORD_CHANGED,MFA_VERIFICATION]Preferred language for resource. Format as described at RFC5646. According to the configured languages codes returned from the
GET /management/v4/{tenantId}/config/ui/languagesAPI.
curl -X 'DELETE'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/cloud_directory/templates/{USER_VERIFICATION}/en'\ -H 'accept: application/json' \ -H 'Authorization: Bearer {IAM_token}''
Response
Status Code
The template was deleted.
The tenant ID is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact a service owner or admin to verify permissions.
The template does not exist.
No Sample Response
Get languages
Get the list of languages that can be used to customize email templates for Cloud Directory.
GET /management/v4/{tenantId}/config/ui/languagesRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
curl -X 'GET'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/ui/languages' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}''
Response
The list of languages that can be used to customize email templates for CLoud Directory.
Status Code
The localization data is returned as a JSON object.
The tenant ID or languages are missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify permissions.
{ "languages": [ "en", "en-US", "fr-FR" ] }
Update languages
Update the list of languages that can be used to customize email templates for Cloud Directory.
PUT /management/v4/{tenantId}/config/ui/languagesRequest
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
User localization configuration. Available languages codes
{
"languages": [
"en",
"en-US",
"fr-FR"
]
}The list of languages that can be used to customize email templates for CLoud Directory.
curl -X 'PUT'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/ui/languages' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}" -H 'Content-Type: application/json' -d '{ "languages": [ "en", "en-US", "fr-FR" ] }'
Response
Status Code
'No content. The localization configuration was updated.'
The tenant ID or request body is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify permissions.
No Sample Response
Get sender details
Get the sender details configuration that is used by Cloud Directory when you are sending emails to your users. Learn more.
GET /management/v4/{tenantId}/config/cloud_directory/sender_detailsRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
curl -X 'GET'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/cloud_directory/sender_details' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}''
Response
The sender details of emails sent to your Cloud Directory users from App ID.
- senderDetails
The sender details of the emails.
- from
The email of the sender.
The name of the sender.
The details that users can use to reply to the emails.
- reply_to
The name to which the users can reply.
The email to which the users can reply.
The expiration data of the link.
Possible values: 900 ≤ value ≤ 604800
Status Code
The sender details configuration for a Cloud Directory email is returned as a JSON object.
The tenant ID parameter is missing or the request is invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
{ "senderDetails": { "from": { "name": "no-reply", "email": "no-reply@appid.cloud.net" }, "reply_to": { "name": "Reply-to", "email": "reply-to@example.com" }, "linkExpirationSec": 86400 } }
Update the sender details
Update the sender details configuration that is used by Cloud Directory when you are sending emails to your users. Learn more.
PUT /management/v4/{tenantId}/config/cloud_directory/sender_detailsRequest
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
A JSON object that contains the sender details.
{
"senderDetails": {
"from": {
"name": "no-reply",
"email": "no-reply@appid.cloud.net"
},
"reply_to": {
"name": "Reply-to",
"email": "reply-to@example.com"
},
"linkExpirationSec": 86400
}
}The sender details of emails sent to your Cloud Directory users from App ID.
- senderDetails
The sender details of the emails.
- from
The email of the sender.
The name of the sender.
The details that users can use to reply to the emails.
- reply_to
The name to which the users can reply.
The email to which the users can reply.
The expiration data of the link.
Possible values: 900 ≤ value ≤ 604800
curl -X 'PUT'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/cloud_directory/sender_details' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}" -H 'Content-Type: application/json' -d '{ "senderDetails": { "from": { "name": "no-reply", "email": "no-reply@appid.cloud.net" }, "reply_to": { "name": "Reply-to", "email": "reply-to@example.com" }, "linkExpirationSec": 86400 } }'
Response
Status Code
No content. The identity provider configuration was updated.
The tenant ID or request body is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
No Sample Response
Get action url
Get the custom url to redirect to when action is run. Learn more.
GET /management/v4/{tenantId}/config/cloud_directory/action_url/{action}Request
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The type of the action. on_user_verified - the URL of your custom user verified page, on_reset_password - the URL of your custom reset password page.
Allowable values: [
on_user_verified,on_reset_password]
curl -X 'GET'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/cloud_directory/action_url/on_user_verified' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}''
Response
The action URL.
Status Code
The action URL is returned as a JSON object.
The tenant ID or action parameters are invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
{ "actionUrl": "https://example.com/myCustomPage" }
Update action url
Update the custom url to redirect to when action is run. Learn more.
PUT /management/v4/{tenantId}/config/cloud_directory/action_url/{action}Request
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The type of the action. on_user_verified - the URL of your custom user verified page, on_reset_password - the URL of your custom reset password page.
Allowable values: [
on_user_verified,on_reset_password]
Form Parameters
The action URL.
curl -X 'PUT'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/cloud_directory/action_url/on_user_verified' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}' -H 'Content-Type: application/x-www-form-urlencoded' -d 'actionUrl=<enter_action_url>'
Response
The action URL.
Status Code
The action url is returned as a JSON object.
The tenant ID or action parameters are invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
{ "actionUrl": "https://example.com/myCustomPage" }
Delete action url
Delete the custom url to redirect to when action is run. Learn more.
DELETE /management/v4/{tenantId}/config/cloud_directory/action_url/{action}Request
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The type of the action. on_user_verified - the URL of your custom user verified page, on_reset_password - the URL of your custom reset password page.
Allowable values: [
on_user_verified,on_reset_password]
curl -X 'DELETE'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/cloud_directory/action_url/{on_user_verified}' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
Status Code
No content. The action url was deleted.
The tenant ID or action parameters are invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact a service owner or admin to verify permissions.
The template does not exist.
No Sample Response
Get password regex
Get the regular expression used by App ID for password strength validation. Learn more.
GET /management/v4/{tenantId}/config/cloud_directory/password_regexRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
curl -X 'GET'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/cloud_directory/password_regex' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
The regular expression that is used by App ID for password strength validation.
The regular expression that is used by App ID for password strength validation encoded in Base64.
The error message.
Possible values: length ≤ 200
Status Code
The defined regex expression escaped rule for acceptable password, base64 encoded regex expression and custom error message are returned as a JSON object.
The tenant ID is invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
{ "base64_encoded_regex": "LipbYS16XS4q", "error_message": "The password must contain at least 1 lowercase alphabetical character", "regex": ".*[a-z].*" }
Update password regex
Update the regular expression used by App ID for password strength validation.
For example, the regular expression: ^[A-Za-z\d]*$ must be passed as:
{
"base64_encoded_regex": "XltBLVphLXpcZF0qJA==",
"error_message": "Must only contain letters and digits"} [Learn more](/docs/appid?topic=appid-cd-strength).
PUT /management/v4/{tenantId}/config/cloud_directory/password_regexRequest
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The Cloud Directory password regex configuration as a JSON object. If the configuration is not set, IBM App ID basic password regex is used.
{
"base64_encoded_regex": "LipbYS16XS4q",
"error_message": "The password must contain at least 1 lowercase alphabetical character"
}The regular expression that is used by App ID for password strength validation.
The regular expression that is used by App ID for password strength validation encoded in Base64.
The error message.
Possible values: length ≤ 200
curl -X 'PUT'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/cloud_directory/password_regex' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}' -H 'Content-Type: application/json' -d '{ "base64_encoded_regex": "Lipbssdkcsjklcq", "error_message": "The password must contain at least 1 lowercase alphabetical character" }
Response
The regular expression that is used by App ID for password strength validation.
The regular expression that is used by App ID for password strength validation encoded in Base64.
The error message.
Possible values: length ≤ 200
Status Code
The password regex was updated.
The tenant ID or password regex parameters are invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
{ "base64_encoded_regex": "LipbYS16XS4q", "error_message": "The password must contain at least 1 lowercase alphabetical character", "regex": ".*[a-z].*" }
Get email dispatcher configuration
Get the configuration of email dispatcher that is used by Cloud Directory when you are sending emails to your users.
GET /management/v4/{tenantId}/config/cloud_directory/email_dispatcherRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
curl -X 'GET'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/cloud_directory/email_dispatcher' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
The email provider.
Possible values: [
sendgrid,custom,appid]The Sendgrid details.
- sendgrid
The Sendgrid API key.
Possible values: length ≤ 100
The custom details.
- custom
The URL.
Possible values: length ≤ 300
The authorization data.
- authorization
The type of authorization.
Possible values: [
value,basic,none]The value.
The username.
The password.
Status Code
The email dispatcher configuration is returned as a JSON object.
The tenant ID is invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
{ "provider": "sendgrid", "sendgrid": { "apiKey": "sendgridApiKey" }, "custom": { "url": "https://custom_email_dispatcher.com/send", "authorization": { "type": "value", "value": "verySecureSecret" } } }
Update email dispatcher configuration
Update the configuration of email dispatcher that is used by Cloud Directory when you are sending emails to your users. You can use your own email provider with App ID. You can use your own Sendgrid account by providing your Sendgrind API key.
Alternatively, you can define a custom email dispatcher by providing App ID with URL. The URL is called for sending emails. If needed, you can determine a specific authorization method – either basic, such as a username and password, or a custom value. By default, App ID's email provider is used. Learn more.
PUT /management/v4/{tenantId}/config/cloud_directory/email_dispatcherRequest
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The Cloud Directory email dispatcher configuration, which is specified as a JSON object.
{
"provider": "sendgrid",
"sendgrid": {
"apiKey": "sendgridApiKey"
},
"custom": {
"url": "https://custom_email_dispatcher.com/send",
"authorization": {
"type": "value",
"value": "verySecureSecret"
}
}
}The email provider.
Allowable values: [
sendgrid,custom,appid]The Sendgrid details.
- sendgrid
The Sendgrid API key.
Possible values: length ≤ 100
The custom details.
- custom
The URL.
Possible values: length ≤ 300
The authorization data.
- authorization
The type of authorization.
Allowable values: [
value,basic,none]The value.
The username.
The password.
curl -X 'PUT'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/cloud_directory/email_dispatcher' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}" -H 'Content-Type: application/json' -d '{ "provider": "sendgrid", "sendgrid": { "apiKey": "SG.xxxxx.yyyyy"" }, "custom": { "url": "https://custom_email_dispatcher.com/send", "authorization": { "type": "value", "value": "verySecureSecret" } } }
Response
The email provider.
Possible values: [
sendgrid,custom,appid]The Sendgrid details.
- sendgrid
The Sendgrid API key.
Possible values: length ≤ 100
The custom details.
- custom
The URL.
Possible values: length ≤ 300
The authorization data.
- authorization
The type of authorization.
Possible values: [
value,basic,none]The value.
The username.
The password.
Status Code
The email dispatcher was updated.
The tenant ID or custom email dispatcher config are invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
{ "provider": "sendgrid", "sendgrid": { "apiKey": "sendgridApiKey" }, "custom": { "url": "https://custom_email_dispatcher.com/send", "authorization": { "type": "value", "value": "verySecureSecret" } } }
Test the email provider configuration
Send a message to a specific email to test your settings.
POST /management/v4/{tenantId}/config/cloud_directory/email_settings/testRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The email dispatcher settings, which are specified as a JSON object.
{
"emailTo": "example@mail.com",
"emailSettings": {
"provider": "sendgrid",
"sendgrid": {
"apiKey": "SG.xxxxx.yyyyy"
}
},
"senderDetails": {
"from": {
"email": "no-reply@mail.com",
"name": "no-reply"
},
"reply_to": {
"email": "reply-to@mail.com",
"name": "Reply-to"
}
}
}The email address to which the email will be sent.
The email settings.
- emailSettings
The email provider.
Allowable values: [
sendgrid,custom]The Sendgrid details.
- sendgrid
The Sendgrid API key.
Possible values: length ≤ 100
The custom details.
- custom
The URL.
Possible values: length ≤ 300
The authorization details.
- authorization
The type of authorization.
Allowable values: [
value,basic,none]The value.
The username.
The password.
The details of the sender.
- senderDetails
The details of the sender.
- from
The email of the sender.
The name of the sender.
The details that users can use to reply to the emails.
- reply_to
The email to which users can reply.
The name to which users can reply.
curl -X 'POST'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/cloud_directory/email_settings/test' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}" -H 'Content-Type: application/json' -d '{ "emailTo": "example@mail.com", "emailSettings": { "provider": "sendgrid", "sendgrid": { "apiKey": "SG.xxxxx.yyyyy" } }, "senderDetails": { "from": { "email": "no-reply@mail.com", "name": "no-reply" }, "reply_to": { "email": "reply-to@mail.com", "name": "Reply-to" } } }
Response
The status of the request.
The status code of the dispatch request.
The response of the dispatcher.
Status Code
The response status code and additional information from the email provider because of a failure are returned as a JSON object.
The tenant ID or request body is invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
{ "success": true, "dispatcherStatusCode": 202 }
Test the email dispatcher configuration
Send a message to a specific email to test your configuration.
POST /management/v4/{tenantId}/config/cloud_directory/email_dispatcher/testRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
Form Parameters
The email address to which you want to send your test message.
curl -X 'POST'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/cloud_directory/email_dispatcher/test' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}" -H 'Content-Type: application/x-www-form-urlencoded' -d 'email=email@example.com'
Response
The status code of the request.
The headers of the email.
Status Code
The response status code and headers from the custom email dispatcher are returned as a JSON object.
The tenant ID or email value is invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
{ "statusCode": 400, "headers": { "server": "nginx", "date": "Tue, 24 Jul 2018 09:50:25 GMT", "content-type": "application/json", "access-control-allow-headers": "Authorization, Content-Type" } }
Test the MFA SMS dispatcher configuration
Send a message to a specific phone number to test your MFA SMS configuration.
POST /management/v4/{tenantId}/config/cloud_directory/sms_dispatcher/testRequest
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The phone number to which you want to send your test SMS message.
The phone number to which you can send a message to test your MFA SMS configuration.
Example:
+1-999-999-9999
curl -X 'POST'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/cloud_directory/sms_dispatcher/test' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}" -H 'Content-Type: application/json' -d '{ "phone_number": "+1-999-999-9999" }'
Response
The confirmation code.
The phone number.
Status Code
The response status code and headers from the SMS dispatcher are returned as a JSON object.
The tenant ID or SMS channel configuration is invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
{ "confirmationCode": 979469, "phoneNumber": "+1-999-999-9999" }
Get APM configuration
Get the configuration of advanced password management.
GET /management/v4/{tenantId}/config/cloud_directory/advanced_password_managementRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
curl -X 'GET'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/cloud_directory/advanced_password_management' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
The configuration of advanced password management.
The configuration details of advanced password management.
- advancedPasswordManagement
The status of the configuration.
The configuration of password reuse.
- passwordReuse
The status of the configuration.
The limits of password reuse.
- config
The maximum times that a password can be reused.
Possible values: 1 ≤ value ≤ 8
The configuration of the prevention of password reuse.
- preventPasswordWithUsername
The status of the configuration.
The configuration of password expiration.
- passwordExpiration
The status of the configuration.
The limits of password expiration.
- config
The expiration limits of passwords.
Possible values: 1 ≤ value ≤ 90
The configuration of the lockout policy.
- lockOutPolicy
The status of the configuration.
The details of the configuration.
- config
The duration of lockout.
Possible values: 60 ≤ value ≤ 86400
The number of failed attempts after which users will be locked out of their accounts.
Possible values: 1 ≤ value ≤ 10
The configuration of the minimum interval for password change.
- minPasswordChangeInterval
The status of the configuration.
The configuration details.
- config
The minimum hours after which users must change their password.
Possible values: 0 ≤ value ≤ 720
Status Code
View the advanced password management configuration.
The tenant ID is invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
{ "advancedPasswordManagement": { "enabled": true, "passwordReuse": { "enabled": true, "config": { "maxPasswordReuse": 8 } }, "preventPasswordWithUsername": { "enabled": true }, "passwordExpiration": { "enabled": true, "config": { "daysToExpire": 30 } }, "lockOutPolicy": { "enabled": true, "config": { "lockOutTimeSec": 1800, "numOfAttempts": 3 } }, "minPasswordChangeInterval": { "enabled": true, "config": { "minHoursToChangePassword": 0 } } } }
Update APM configuration
Update the advanced password management configuration for the provided tenant ID. By enabling the configuration, any authentication event is also charged as advanced security event. Learn more.
PUT /management/v4/{tenantId}/config/cloud_directory/advanced_password_managementRequest
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The Cloud Directory APM configuration, which is specified as a JSON object.
{
"advancedPasswordManagement": {
"enabled": true,
"passwordReuse": {
"enabled": true,
"config": {
"maxPasswordReuse": 8
}
},
"preventPasswordWithUsername": {
"enabled": true
},
"passwordExpiration": {
"enabled": true,
"config": {
"daysToExpire": 30
}
},
"lockOutPolicy": {
"enabled": true,
"config": {
"lockOutTimeSec": 1800,
"numOfAttempts": 3
}
},
"minPasswordChangeInterval": {
"enabled": true,
"config": {
"minHoursToChangePassword": 0
}
}
}
}The configuration details of advanced password management.
- advancedPasswordManagement
The status of the configuration.
The configuration of password reuse.
- passwordReuse
The status of the configuration.
The limits of password reuse.
- config
The maximum times that a password can be reused.
Possible values: 1 ≤ value ≤ 8
The configuration of the prevention of password reuse.
- preventPasswordWithUsername
The status of the configuration.
The configuration of password expiration.
- passwordExpiration
The status of the configuration.
The limits of password expiration.
- config
The expiration limits of passwords.
Possible values: 1 ≤ value ≤ 90
The configuration of the lockout policy.
- lockOutPolicy
The status of the configuration.
The details of the configuration.
- config
The duration of lockout.
Possible values: 60 ≤ value ≤ 86400
The number of failed attempts after which users will be locked out of their accounts.
Possible values: 1 ≤ value ≤ 10
The configuration of the minimum interval for password change.
- minPasswordChangeInterval
The status of the configuration.
The configuration details.
- config
The minimum hours after which users must change their password.
Possible values: 0 ≤ value ≤ 720
curl -X 'PUT'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/cloud_directory/advanced_password_management' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}" -H 'Content-Type: application/json' -d '{ "advancedPasswordManagement": { "enabled": true, "passwordReuse": { "enabled": true, "config": { "maxPasswordReuse": 8 } }, "preventPasswordWithUsername": { "enabled": true }, "passwordExpiration": { "enabled": true, "config": { "daysToExpire": 30 } }, "lockOutPolicy": { "enabled": true, "config": { "lockOutTimeSec": 1800, "numOfAttempts": 3 } }, "minPasswordChangeInterval": { "enabled": true, "config": { "minHoursToChangePassword": 0 } } } }'
Response
The configuration of advanced password management.
The configuration details of advanced password management.
- advancedPasswordManagement
The status of the configuration.
The configuration of password reuse.
- passwordReuse
The status of the configuration.
The limits of password reuse.
- config
The maximum times that a password can be reused.
Possible values: 1 ≤ value ≤ 8
The configuration of the prevention of password reuse.
- preventPasswordWithUsername
The status of the configuration.
The configuration of password expiration.
- passwordExpiration
The status of the configuration.
The limits of password expiration.
- config
The expiration limits of passwords.
Possible values: 1 ≤ value ≤ 90
The configuration of the lockout policy.
- lockOutPolicy
The status of the configuration.
The details of the configuration.
- config
The duration of lockout.
Possible values: 60 ≤ value ≤ 86400
The number of failed attempts after which users will be locked out of their accounts.
Possible values: 1 ≤ value ≤ 10
The configuration of the minimum interval for password change.
- minPasswordChangeInterval
The status of the configuration.
The configuration details.
- config
The minimum hours after which users must change their password.
Possible values: 0 ≤ value ≤ 720
Status Code
The advanced password management configuration is updated.
The tenant ID or advanced password management configuration is invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
{ "advancedPasswordManagement": { "enabled": true, "passwordReuse": { "enabled": true, "config": { "maxPasswordReuse": 8 } }, "preventPasswordWithUsername": { "enabled": true }, "passwordExpiration": { "enabled": true, "config": { "daysToExpire": 30 } }, "lockOutPolicy": { "enabled": true, "config": { "lockOutTimeSec": 1800, "numOfAttempts": 3 } }, "minPasswordChangeInterval": { "enabled": true, "config": { "minHoursToChangePassword": 0 } } } }
Get tenant audit status
Get a JSON object that contains the auditing status of the tenant.
GET /management/v4/{tenantId}/config/capture_runtime_activityRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
curl -X 'GET'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/capture_runtime_activity' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
Status Code
The auditing status of the tenant is returned as a JSON object.
The tenant ID is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify permissions.
{ "isActive": true }
Update tenant audit status
Capture app user sign-in's, sign-up's, and other runtime events in Cloud Logs that you can search, analyze, and report. By turning on Cloud Logs, any authentication event is also charged as advanced security event. IBM Cloud Logs is available in select regions. Learn more.
PUT /management/v4/{tenantId}/config/capture_runtime_activityRequest
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The new audit status, which is specified as a JSON object.
The status of the configuration.
Example:
true
curl -X 'PUT' \'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/capture_runtime_activity' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}' -H 'Content-Type: application/json' -d '{ "isActive": true }'
Response
Status Code
The tenant was updated.
The tenant ID or request body is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
No Sample Response
Get channels
Get all the MFA channels registered with the App ID Instance.
GET /management/v4/{tenantId}/config/cloud_directory/mfa/channelsRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
curl -X 'GET'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/cloud_directory/mfa/channels' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
A list of all the MFA channels that are registered with a specific App ID instance.
- channels
The type of channel.
The status of the configuration.
The configuration of the mfa channel.
- config
The key.
The secret.
The sender details.
The provider.
Status Code
A list of all the MFA channels that are registered with the App ID tenant ID is returned as a JSON object.
The tenant ID is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify permissions.
{ "channels": [ { "isActive": true, "type": "email" }, { "isActive": false, "type": "sms", "config": { "key": "key", "secret": "secret", "from": 1234567890, "provider": "nexmo" } } ] }
Get channel
Get a specific MFA channel registered with the App ID Instance.
GET /management/v4/{tenantId}/config/cloud_directory/mfa/channels/{channel}Request
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The MFA channel.
Allowable values: [
email,nexmo]
curl -X 'GET'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/cloud_directory/mfa/channels/email' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
The status of the configuration.
The type of channel.
The configuration of the channel.
- config
The key.
The secret.
The sender details.
The provider.
Status Code
A specific channel that is registered with the App ID tenant ID is returned as a JSON object.
The tenant ID is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify permissions.
[ { "isActive": false, "type": "sms", "config": { "key": "key", "secret": "secret", "from": "1234567890", "provider": "nexmo" } } ]
Update channel
Enable or disable a registered MFA channel on the App ID instance. Learn more.
PUT /management/v4/{tenantId}/config/cloud_directory/mfa/channels/{channel}Request
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The MFA channel.
Allowable values: [
email,nexmo]
The MFA channel payload.
The status of the configuration.
Example:
trueThe details of the configuration.
Examples:{ "key": "key", "secret": "secret", "from": "1234567890" }
curl -X 'PUT'\'https://{region}.appid.cloud.ibm.com/management/management/v4/{tenant_ID}/config/cloud_directory/mfa/channels/email' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}' -H 'Content-Type: application/json' -d '{ "isActive": true, "config": { "key": "key", "secret": "secret", "from": "1234567890" } }'
Response
The status of the configuration.
The type of channel.
The configuration of the channel.
- config
The key.
The secret.
The sender details.
The provider.
Status Code
The updated channel data is returned as a JSON object.
The tenant ID or request body is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
The channel was not be found.
Returned because of an internal server error.
[ { "isActive": false, "type": "sms", "config": { "key": "key", "secret": "secret", "from": "1234567890", "provider": "nexmo" } } ]
Get an extension configuration
View a registered extension's configuration for an instance of App ID. Learn more.
GET /management/v4/{tenantId}/config/cloud_directory/mfa/extensions/{name}Request
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The name of the extension.
Allowable values: [
premfa,postmfa]
curl -X 'GET'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/cloud_directory/mfa/extensions/premfa' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
The status of the configuration.
The congiguration details of a registered extension.
- config
The extension's URL.
The headers.
Status Code
The extension configuration is returned as a JSON object.
The tenant ID or request body is either missing or invalid.
The request is unauthorized. Be sure that you pass a valid IAM token in the authorization header of your request.
You have insufficient permissions. Contact your administrator or service owner to verify your permissions.
Internal server error. Try again in a few minutes.
{ "isActive": true, "config": { "url": "https://example.com/extension", "headers": { "authorization": "Bearer <token>" } } }
Update an extension configuration
Set or update a registered extension's configuration for an instance of App ID. Learn more.
PUT /management/v4/{tenantId}/config/cloud_directory/mfa/extensions/{name}Request
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The name of the extension.
Allowable values: [
premfa,postmfa]
The extension configuration payload.
{
"isActive": true,
"config": {
"url": "https://example.com/extension",
"headers": {
"authorization": "Bearer <token>"
}
}
}The status of the configuration.
The congiguration details of a registered extension.
- config
The extension's URL.
The headers.
curl -X 'PUT'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/cloud_directory/mfa/extensions/premfa' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}' -H 'Content-Type: application/json' -d '{ "isActive": true, "config": { "url": "https://example.com/extension", "headers": { "authorization": "Bearer <IAM_token>" } } }'
Response
The status of the configuration.
The congiguration details of a registered extension.
- config
The extension's URL.
The headers.
Status Code
A JSON object that contains either true or false is returned, depending on your configuration.
The tenant ID or request body is either missing or invalid.
The request is unauthorized. Be sure that you pass a valid IAM token in the authorization header of your request.
You have insufficient permissions. Contact your administrator or service owner to verify your permissions.
Internal server error. Try again in a few minutes.
{ "isActive": true, "config": { "url": "https://example.com/extension", "headers": { "authorization": "Bearer <token>" } } }
Enable or disable an extension
Update the status of a registered extension for an instance of App ID to enabled or disabled. Learn more.
PUT /management/v4/{tenantId}/config/cloud_directory/mfa/extensions/{name}/activeRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The name of the extension.
Allowable values: [
premfa,postmfa]
The extension enabled.
{
"isActive": true
}The status of the configuration.
Example:
trueThe configuration details of the registered extension.
curl -X 'PUT'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenantId}/config/cloud_directory/mfa/extensions/premfa/active' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}' -H 'Content-Type: application/json' -d '{ "isActive": true }'
Response
The status of the configuration.
Example:
trueThe configuration details of the registered extension.
Status Code
A JSON object that contains either true or false is returned, depending on your configuration.
The tenant ID or request body is either missing or invalid.
The request is unauthorized. Be sure that you pass a valid IAM token in the authorization header of your request.
You have insufficient permissions. Contact your administrator or service owner to verify your permissions.
Internal server error. Try again in a few minutes.
{ "isActive": true }
Test the extension configuration
Test an extension configuration. Learn more.
POST /management/v4/{tenantId}/config/cloud_directory/mfa/extensions/{name}/testRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The name of the extension.
Allowable values: [
premfa,postmfa]
curl -X 'POST'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenantId}/config/cloud_directory/mfa/extensions/premfa/test' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}' -d ''
Response
The status code of the test.
The response headers.
Status Code
The response status code, the response body, and headers from the extension's URL are returned.
The tenant ID or extension name is missing or invalid.
The request is unauthorized. Be sure that you pass a valid IAM token in the authorization header of your request.
You have insufficient permissions. Contact your administrator or service owner to verify your permissions.
{ "statusCode": 200, "responseBody": { "skipMfa": true }, "responseHeaders": { "content-type": "application/json", "date": "Tue, 24 Jul 2018 09:50:25 GMT" } }
Get MFA configuration
Get the MFA configuration registered with the App ID Instance.
GET /management/v4/{tenantId}/config/cloud_directory/mfaRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
curl -X 'GET'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/cloud_directory/mfa' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
The status of the configuration.
Status Code
The MFA configuration that is registered with the App ID tenant is returned as a JSON object.
The tenant ID is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify permissions.
{ "isActive": true }
Update MFA configuration
Update MFA configuration on the App ID instance.
PUT /management/v4/{tenantId}/config/cloud_directory/mfaRequest
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The MFA configuration payload.
{
"isActive": true
}The status of the configuration.
Example:
trueThe configuration details of the MFA channel.
curl -X 'PUT'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/cloud_directory/mfa' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}' -H 'Content-Type: application/json' -d '{ "isActive": true }'
Response
The status of the configuration.
Status Code
The updated MFA configuration data is returned as a JSON object.
The tenant ID or request body is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
Returned because of an internal server error.
{ "isActive": true }
Get SSO configuration
View the Single sign-on (SSO) configuration registered with the App ID Instance.
GET /management/v4/{tenantId}/config/cloud_directory/ssoRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
curl -X 'GET' \'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/cloud_directory/sso' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
Status Code
The SSO configuration that is registered with the App ID tenant ID is returned as a JSON object.
The tenant ID is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify permissions.
{ "isActive": true, "inactivityTimeoutSeconds": 86400, "logoutRedirectUris": [ "http://localhost:3000/logout-callback" ] }
Update SSO configuration
Update the Single sign-on (SSO) configuration on the App ID instance. Learn more.
PUT /management/v4/{tenantId}/config/cloud_directory/ssoRequest
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The SSO configuration payload.
The status of the configuration.
Example:
trueThe time limit of activity after which users are logged out of their account.
Possible values: 0 ≤ value ≤ 604800
Example:
86400The logout redirect URL.
curl -X 'PUT'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/cloud_directory/sso' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}' -H 'Content-Type: application/json' -d '{ "isActive": true, "inactivityTimeoutSeconds": 86400, "logoutRedirectUris": [ "http://localhost:3000/logout-callback" ] }'
Response
Status Code
The updated SSO configuration data is returned as a JSON object.
The tenant ID or request body is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
Returned because of an internal server error.
{ "isActive": true, "inactivityTimeoutSeconds": 86400, "logoutRedirectUris": [ "http://localhost:3000/logout-callback" ] }
Get the rate limit configuration
Get the rate limit configuration registered with the App ID Instance.
GET /management/v4/{tenantId}/config/cloud_directory/rate_limitRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
curl -X 'GET'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/cloud_directory/rate_limit' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
Status Code
The rate limit configuration that is registered with the App ID tenant is returned as a JSON object.
The tenant ID or request body is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
{ "signUpLimitPerMinute": 50, "signInLimitPerMinute": 60 }
Update the rate limit configuration
Update the rate limit configuration on the App ID instance. Learn more.
PUT /management/v4/{tenantId}/config/cloud_directory/rate_limitRequest
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The rate limit configuration payload.
The sign-up limit per minute.
Possible values: 0 ≤ value ≤ 4294967295
Example:
50The sign-in limit per minute.
Possible values: 0 ≤ value ≤ 4294967295
Example:
60
curl -X 'PUT'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/config/cloud_directory/rate_limit' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}' -H 'Content-Type: application/json' -d '{ "signUpLimitPerMinute": 50, "signInLimitPerMinute": 60 }'
Response
Status Code
The updated rate limit configuration data is returned as a JSON object.
The tenant ID or request body is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
{ "signUpLimitPerMinute": 50, "signInLimitPerMinute": 60 }
Sign up
Start the sign-up process. Learn more.
POST /management/v4/{tenantId}/cloud_directory/sign_upRequest
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
Query Parameters
A boolean indication if a profile must be created for the Cloud Directory user.
Preferred language for resource. Format as described at RFC5646.
Default:
en
The stored Cloud Directory user data.
The email details.
The password.
Example:
userPasswordThe user's username.
Possible values: length ≤ 200
Example:
myUserNameThe status of the request. Accepted values "PENDING" or "CONFIRMED".
Example:
PENDING
curl -X 'POST'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/cloud_directory/sign_up?shouldCreateProfile={true}&language=en' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}" -H 'Content-Type: application/json' -d '{ "active": true, "emails": [ { "value": "email@example.com", "primary": true } ], "userName": "user_name", "password": "userPassword" }'
Response
Status Code
The new Cloud Directory user data is returned as a JSON object. Full user data can be found here{: external}.
The tenant ID or request body is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
The email address exists.
{ "displayName": "John Doe", "active": true, "emails": [ { "value": "johndoe@example.com", "primary": true } ], "meta": { "created": "2019-05-29T12:45:30.671Z", "lastModified": "2019-05-29T12:45:30.671Z", "resourceType": "User" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "name": { "givenName": "John", "familyName": "Doe", "formatted": "John Doe" }, "id": "66ad3522-2251-4531-abff-3e3aad66b650" }
Get signup confirmation result
Get the sign-up confirmation result. Learn more.
POST /management/v4/{tenantId}/cloud_directory/sign_up/confirmation_resultRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
Form Parameters
The context that is used to get the verification or forgot password confirmation result.
curl -X 'POST'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/cloud_directory/sign_up/confirmation_result' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}" -H 'Content-Type: application/x-www-form-urlencoded' -d 'context=context'
Response
The status of the request.
The user's unique ID.
Status Code
The sign-up confirmation result is returned as a JSON object.
The tenant ID or context is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
The context was not found.
{ "success": true, "uuid": "773f85b4-72f4-480d-aca8-755f517c4508" }{ "errorCode": "NOT_FOUND", "message": "context was not found" }
Forgot password
Start the forgot password process. Learn more.
POST /management/v4/{tenantId}/cloud_directory/forgot_passwordRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
Query Parameters
Preferred language for resource. Format as described at RFC5646.
Default:
en
Form Parameters
The user identifier - email or userName based on the identityField property in cloud directory configuration.
Possible values: length ≤ 200
curl -X 'POST'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/cloud_directory/forgot_password?language=en' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}" -H 'Content-Type: application/x-www-form-urlencoded' -d 'user=user@example.com'
Response
Status Code
The Cloud Directory user data is returned as a JSON object. Full user data can be found here{: external}.
The tenant ID or request body is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
The user account was not verified.
{ "displayName": "John Doe", "active": true, "emails": [ { "value": "johndoe@example.com", "primary": true } ], "meta": { "created": "2019-05-29T12:45:30.671Z", "lastModified": "2019-05-29T12:45:30.671Z", "resourceType": "User" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "name": { "givenName": "John", "familyName": "Doe", "formatted": "John Doe" }, "id": "66ad3522-2251-4531-abff-3e3aad66b650" }
Forgot password confirmation result
Get the forgot password flow confirmation result. Learn more.
POST /management/v4/{tenantId}/cloud_directory/forgot_password/confirmation_resultRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
Form Parameters
The context that is used to get the verification or forgot password confirmation result.
curl -X 'POST'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenantId}/cloud_directory/forgot_password/confirmation_result' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}" -H 'Content-Type: application/x-www-form-urlencoded' -d 'context=context'
Response
The status of the request.
The user's unique ID.
Status Code
The forgot password confirmation result is returned as a JSON object.
The tenant ID or context is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
The context was not found.
{ "success": true, "uuid": "773f85b4-72f4-480d-aca8-755f517c4508" }{ "errorCode": "NOT_FOUND", "message": "context was not found" }
Change password
Change the Cloud Directory user password. Learn more.
POST /management/v4/{tenantId}/cloud_directory/change_passwordRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
Query Parameters
Preferred language for resource. Format as described at RFC5646.
Default:
en
Form Parameters
The new password.
The Cloud Directory unique user Id.
The IP address and the changed password.
curl -X 'POST'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenantId}/cloud_directory/change_password?language=en' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}" -H 'Content-Type: application/x-www-form-urlencoded' -d 'newPassword=new_password.&uuid=unique_user_id'
Response
Status Code
The Cloud Directory user data is returned as a JSON object. Full user data can be found here{: external}.
The tenant ID, uuid, or newPassword is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
{ "displayName": "John Doe", "active": true, "emails": [ { "value": "johndoe@example.com", "primary": true } ], "meta": { "created": "2019-05-29T12:45:30.671Z", "lastModified": "2019-05-29T12:45:30.671Z", "resourceType": "User" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "name": { "givenName": "John", "familyName": "Doe", "formatted": "John Doe" }, "id": "66ad3522-2251-4531-abff-3e3aad66b650" }
Resend user notifications
Resend user email notifications (for example, resend user verification email). Learn more.
POST /management/v4/{tenantId}/cloud_directory/resend/{templateName}Request
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The type of email template. The type can be "USER_VERIFICATION", "WELCOME", "PASSWORD_CHANGED" or "RESET_PASSWORD".
Allowable values: [
USER_VERIFICATION,RESET_PASSWORD,WELCOME,PASSWORD_CHANGED]
Query Parameters
Preferred language for resource. Format as described at RFC5646.
Default:
en
Form Parameters
The Cloud Directory unique user Id.
curl -X 'POST'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenantId}/cloud_directory/resend/USER_VERIFICATION?language=en' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}" -H 'Content-Type: application/x-www-form-urlencoded' -d 'uuid=unique_user_id'
Response
The message of the notification sent to the user.
Status Code
The notification is sent.
The tenant ID or request body is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
The user account is not verified in cases when the template name is RESET_PASSOWRD.
The user account is already confirmed in cases when the template name is CONFIRMATION.
{ "message": "Email is queued to be delivered." }
Delete Cloud Directory User and Profile
Delete an existing Cloud Directory user and the associated profile. Learn more. Note: This action cannot be undone.
DELETE /management/v4/{tenantId}/cloud_directory/remove/{userId}Request
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The ID assigned to a user when they sign in by using Cloud Directory. You can find the userId by navigating to App ID > Cloud Directory > Users in the UI and clicking the user's email.
curl -X 'DELETE' \'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/cloud_directory/remove/{userId}' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}''
Get recent activity
This endpoint is deprecated, use recent_authentications_hidden instead.
GET /management/v4/{tenantId}/recent_authenticationsRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
Response
The identity provider.
Example:
FacebookThe user's display name.
Example:
App ID UserThe timestamp.
Example:
1495024442136
Status Code
An array of recent activity is returned as a JSON object.
The tenant ID parameter is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify permissions.
No Sample Response
Get recent activity
Get the recent activity for the App ID instance. Learn more.
GET /management/v4/{tenantId}/recent_authentications_hiddenRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
curl -X 'GET'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/recent_authentications_hidden' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}''
Response
The details of the recent activity for the App instance.
- results
The identity provider.
Example:
FacebookThe display name of the user.
Example:
App ID UserThe timestamp.
Example:
1495024442136
Status Code
An array of recent activity is returned as a JSON object.
The tenant ID parameter is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify permissions.
No Sample Response
Search users
Get the list of users. If you provide the email or ID, you can view only users that match the email or ID, not including anonymous profiles. Learn more.
GET /management/v4/{tenantId}/usersRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
Query Parameters
The user data.
Allowable values: [
index,full]Email (as retrieved from the Identity Provider).
The IdP specific user identifier.
The first result in a set list of results.
The maximum number of results per page.
Possible values: 0 ≤ value ≤ 100
curl -X 'GET'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/users?dataScope=index' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
The number of search results.
The number of items per page.
The details of the request options.
- requestOptions
The start index.
The count.
The user details.
- users
The user ID.
The user's identity provider.
The user's email.
Status Code
An array of results is returned as a JSON object.
The tenant ID is missing or invalid, or the request is missing the email or ID.
The request is unauthorized by the platform. To be authorized, an IAM token with the valid permissions must be provided in the authorization header of your request.
You are not authorized to complete this operation. Contact the service owner or admin to verify your permissions.
Returned because of an internal server error.
{ "totalResults": 7, "itemsPerPage": 3, "requestOptions": { "startIndex": 5, "count": 5 }, "users": [ { "idp": "cloud_directory", "id": "e782661a-efdb-4540-9ed8-d6a3e26713ca", "email": "your@mail.com" }, { "idp": "facebook", "id": "d6f32b32-90d9-4d60-82f2-f503bc244174", "email": "your@mail.com" }, { "idp": "google", "id": "238c75c4-38ea-4de8-b5d4-338744d83b0f", "email": "your@mail.com" } ] }
Pre-register a user profile
Create a profile for a user that you know needs access to your app before they sign in to your app for the first time. Learn more.
POST /management/v4/{tenantId}/usersRequest
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The user configuration and attributes.
The identity provider.
Allowable values: [
saml,cloud_directory,facebook,google,appid_custom,ibmid]Example:
samlThe identity details of the user.
Possible values: length ≥ 1
Example:
appid@ibm.comThe profile.
- profile
The custom attributes.
Examples:{ "points": "150" }- attributes
curl -X 'POST'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/users' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}" -H 'Content-Type: application/json' -d '{ "idp": "saml", "idp-identity": "email@example.com", "profile": { "attributes": { "points": "150" } } }'
Response
Status Code
View the ID of the created user.
The tenant ID, IdP type, or IdP identity ID is missing or invalid.
The request is unauthorized by the platform. To be authorized, an IAM token with the valid permissions must be provided in Authorization header.
You are not authorized to complete this operation. Contact the service owner or admin to verify your permissions.
The user ID for the provided IdP exists.
Returned because of an internal server error.
{ "id": "111c22c3-38ea-4de8-b5d4-338744d83b0f" }
Export user profiles
Export App ID user profiles, not including Cloud Directory and anonymous users. Learn more.
GET /management/v4/{tenantId}/users/exportRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
Query Parameters
The first result in a set list of results.
The maximum number of results per page.
Possible values: 0 ≤ value ≤ 100
curl -X 'GET'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/users/export' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
The list of App ID user profiles, not including Cloud Directory and anonymous users.
Possible values: number of items ≤ 50
- users
The user's ID.
The details of the user's identity.
- identities
The user's identity provider.
The identity provider's ID.
The user's identity information.
The user's profile attributes.
The user's name.
The user's email.
The user's picture.
The user's gender.
The user's locale.
The user's preferred username.
The user's identity provider.
The hashed ID of the identity provider.
The hashed email.
The roles.
Status Code
View a list of the App ID user profiles. You can see up to 50 users per request.
The tenant ID is missing or invalid.
The request is unauthorized by the platform. To be authorized, an IAM token with the valid permissions must be provided in the authorization header.
You are not authorized to complete this operation. Contact the service owner or admin to verify your permissions.
The tenant ID is not found.
{ "itemsPerPage": 2, "totalResults": 2, "requestOptions": {}, "users": [ { "id": "7ae804f3-0ed3-45f0-bc6b-1c6af868e6d6", "name": "App ID Google User profile", "email": "your@mail.com", "identities": [ { "provider": "google", "id": "105646725068605084546", "idpUserInfo": { "id": "105646725068605084546", "email": "your@mail.com", "picture": "profilePic.jpg" } } ], "attributes": { "points": 150 }, "roles": [] }, { "id": "1439d777-185d-4be1-8f4a-c4e8142b87ea", "name": "App ID Facebook User profile", "email": "mail@mail.com", "identities": [ { "provider": "facebook", "id": "100195207128541", "picture": { "data": { "height": 50, "width": 50, "url": "https://profilePic.com" } }, "first_name": "AppID", "last_name": "Development" } ], "attributes": { "points": 250 }, "roles": [ "adult", "child" ] } ] }
Import user profiles
Import App ID user profiles, not including Cloud Directory and anonymous users. Learn more.
POST /management/v4/{tenantId}/users/importRequest
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The exported users as a JSON object (as returned by the export endpoint).
{
"itemsPerPage": 2,
"totalResults": 2,
"requestOptions": {},
"users": [
{
"id": "7ae804f3-0ed3-45f0-bc6b-1c6af868e6d6",
"name": "App ID Google User profile",
"email": "your@mail.com",
"identities": [
{
"provider": "google",
"id": "105646725068605084546",
"idpUserInfo": {
"id": "105646725068605084546",
"email": "your@mail.com",
"picture": "profilePic.jpg"
}
}
],
"attributes": {
"points": 150
},
"roles": []
},
{
"id": "1439d777-185d-4be1-8f4a-c4e8142b87ea",
"name": "App ID Facebook User profile",
"email": "mail@mail.com",
"identities": [
{
"provider": "facebook",
"id": "100195207128541",
"picture": {
"data": {
"height": 50,
"width": 50,
"url": "https://profilePic.com"
}
},
"first_name": "AppID",
"last_name": "Development"
}
],
"attributes": {
"points": 250
},
"roles": [
"adult",
"child"
]
}
]
}The list of App ID user profiles, not including Cloud Directory and anonymous users.
Possible values: number of items ≤ 50
- users
The user's ID.
The details of the user's identity.
- identities
The user's identity provider.
The identity provider's ID.
The user's identity information.
The user's profile attributes.
The user's name.
The user's email.
The user's picture.
The user's gender.
The user's locale.
The user's preferred username.
The user's identity provider.
The hashed ID of the identity provider.
The hashed email.
The roles.
curl -X 'POST'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenantId}/users/import' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}" -H 'Content-Type: application/json' -d '{ "itemsPerPage": 2, "totalResults": 2, "requestOptions": {}, "users": [ { "id": "7a1c6af868e6d6", "name": "App ID Google User profile", "email": "your@mail.com", "identities": [ { "provider": "google", "id": "105646725068605084546", "idpUserInfo": { "id": "105646725068605084546", "email": "your@mail.com", "picture": "profilePic.jpg" } } ], "attributes": { "points": 150 }, "roles": [] }, { "id": "1439d777185dc4e8142b87ea", "name": "App ID Facebook User profile", "email": "mail@mail.com", "identities": [ { "provider": "facebook", "id": "100195207128541", "picture": { "data": { "height": 50, "width": 50, "url": "https://profilePic.com" } }, "first_name": "AppID", "last_name": "Development" } ], "attributes": { "points": 250 }, "roles": [ "adult", "child" ] } ] }'
Response
The number of added user profiles.
THe number of user profiles that failed to import.
The reasons why user profiles failed to import.
- failReasons
The original profile ID.
THe identity provider.
The error message that indicates the reasons why user profiles failed to import.
Status Code
Import users from another instance of App ID. The format for import is the same format in which the users are exported from the initial instance. You can add up to 50 users per request.
The tenant ID or request body is missing or invalid.
The request is unauthorized by the platform. To be authorized, an IAM token with the valid permissions must be provided in the authorization header of your request.
You are not authorized to complete this operation. Contact the service owner or admin to verify your permissions.
The tenant ID is not found.
{ "added": 30, "failed": 1, "failReasons": [ { "originalId": "773f85b4-72f4-480d-aca8-755f517c4508", "idp": "facebook", "error": { "message": "The user exists." } } ] }
Request
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The user's identifier ('subject' in identity token). You can find the userProfileId by navigating to App ID > Cloud Directory > Users in the UI and clicking the user's email.
curl -X 'DELETE'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/users/export' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
Status Code
The user was deleted successfully.
The tenant ID or user ID is missing or invalid.
The request is unauthorized by the platform. To be authorized, an IAM token with the valid permissions must be provided in the authorization header of your request.
You are not authorized to complete this operation. Contact the service owner or admin to verify your permissions.
The user is not found.
Returned because of an internal server error.
No Sample Response
Revoke refresh token
Revoke all the refresh tokens that are issued for the specific user. Learn more.
POST /management/v4/{tenantId}/users/{id}/revoke_refresh_tokenRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The user's identifier ('subject' in identity token). You can find the userProfileId by navigating to App ID > Cloud Directory > Users in the UI and clicking the user's email.
curl -X 'POST'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/users/{id}/revoke_refresh_token' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}' -H 'Content-Type: application/json' -d ''
Response
Status Code
No content. The users refresh token was revoked.
The tenant ID or user ID is missing or invalid.
The request is unauthorized by the platform. To be authorized, an IAM token with the valid permissions must be provided in the authorization header.
You are not authorized to complete this operation. Contact the service owner or admin to verify your permissions.
The user is not found.
Returned because of an internal server error.
No Sample Response
Get user profile
Get the profile of a specific user. Learn more.
GET /management/v4/{tenantId}/users/{id}/profileRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The user's identifier ('subject' in identity token). You can find the userProfileId by navigating to App ID > Cloud Directory > Users in the UI and clicking the user's email.
curl -X 'GET' \'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/users/{id}/profile' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
Status Code
The user profile is returned as a JSON object.
The tenant ID or ID is missing or invalid.
The request is unauthorized by the platform. To be authorized, an IAM token with the valid permissions must be provided in the authorization header of your request.
You are not authorized to complete this operation. Contact the service owner or admin to verify your permissions.
The user is not found.
Returned because of an internal server error.
{ "id": "111c22c3-38ea-4de8-b5d4-338744d83b0f", "name": "John Doe", "email": "johndoe@gmail.com", "picture": "https://lh5.googleusercontent.com/-dddddddQ/AAAAAAAAAAI/AAAAAAAAAAA/jondohw/photo.jpg", "gender": "male", "identities": [ { "provider": "google", "id": "12341234123412341234", "idpUserInfo": { "id": "12341234123412341234", "email": "johndoe@gmail.com", "verified_email": true, "name": "John Doe", "given_name": "John", "family_name": "Doe", "link": "https://plus.google.com/12341234123412341234", "picture": "https://lh5.googleusercontent.com/-dddddddQ/AAAAAAAAAAI/AAAAAAAAAAA/jondohw/photo.jpg", "gender": "male", "idpType": "google" } } ], "attributes": { "points": "150" } }
Update user profile
Update a user profile. Learn more.
PUT /management/v4/{tenantId}/users/{id}/profileRequest
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The user's identifier ('subject' in identity token). You can find the userProfileId by navigating to App ID > Cloud Directory > Users in the UI and clicking the user's email.
The user's profile as a JSON object. Only the 'attributes' field is accepted.
The profile attributes.
Examples:{ "points": "150" }
curl -X 'PUT'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/users/{id}/profile' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}' -H 'Content-Type: application/json' -d '{ "attributes": { "points":"150" } }'
Response
Status Code
The updated user profile is returned as a JSON object.
The tenant ID, user ID, or request body is missing or invalid.
The request is unauthorized by the platform. To be authorized, an IAM token with the valid permissions must be provided in the authorization header of your request.
You are not authorized to complete this operation. Contact the service owner or admin to verify your permissions.
The user is not found.
Returned because of an internal server error.
{ "id": "111c22c3-38ea-4de8-b5d4-338744d83b0f", "name": "John Doe", "email": "johndoe@gmail.com", "picture": "https://lh5.googleusercontent.com/-dddddddQ/AAAAAAAAAAI/AAAAAAAAAAA/jondohw/photo.jpg", "gender": "male", "identities": [ { "provider": "google", "id": "12341234123412341234", "idpUserInfo": { "id": "12341234123412341234", "email": "johndoe@gmail.com", "verified_email": true, "name": "John Doe", "given_name": "John", "family_name": "Doe", "link": "https://plus.google.com/12341234123412341234", "picture": "https://lh5.googleusercontent.com/-dddddddQ/AAAAAAAAAAI/AAAAAAAAAAA/jondohw/photo.jpg", "gender": "male", "idpType": "google" } } ], "attributes": { "points": "150" } }
Get a user's roles
View a list of roles that are associated with a specific user.
GET /management/v4/{tenantId}/users/{id}/rolesRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The user's identifier ('subject' in identity token). You can find the userProfileId by navigating to App ID > Cloud Directory > Users in the UI and clicking the user's email.
curl -X 'GET'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/users/{id}/roles' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
The user's roles.
- roles
The role ID.
Example:
111c22c3-38ea-4de8-b5d4-338744d83b0fThe role name.
Example:
adult
Status Code
The list of roles is returned as a JSON object.
The tenant ID or user ID is missing or invalid.
The request is unauthorized. Be sure that you pass a valid IAM token in the authorization header of your request.
You have insufficient permissions. Contact your administrator to verify your permissions.
The user wasn't found.
No Sample Response
Update a user's roles
Update which roles are associated with a specific user or assign a role to a user for the first time. Learn more.
PUT /management/v4/{tenantId}/users/{id}/rolesRequest
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The user's identifier ('subject' in identity token). You can find the userProfileId by navigating to App ID > Cloud Directory > Users in the UI and clicking the user's email.
A JSON array of roles. The Array can have either names or IDs but not both.
The user's roles.
- roles
The role IDs.
Possible values: number of items ≤ 50
curl -X 'PUT' \'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/users/{id}/roles' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}' -H 'Content-Type: application/json' -d '{ "roles": { "ids": [ "338744d83b0f" ] } }'
Response
The user's roles.
Possible values: number of items ≤ 50
- roles
The role ID.
Example:
111c22c3-38ea-4de8-b5d4-338744d83b0fThe role name.
Example:
child
Status Code
The role is successfully associated with the user.
The tenant ID or user ID is missing or invalid.
The request is unauthorized. Be sure that you pass a valid IAM token in the authorization header of your request.
You have insufficient permissions. Contact your administrator to verify your permissions.
One or more of the roles that you want to assign was not found. List all of your available roles by calling the Roles API.
No Sample Response
Export all Cloud Directory users
Export all of the Cloud Directory users who are associated with a specific App ID instance. You can track the export status of your request as needed. When the export is ready or if the request fails, an email is sent to the email address provided.
If the request is successful, you can download a JSON file that contains the exported list of users that you can import into another App ID instance with the import all users endpoint. To access the requested data, download the exported file of all Cloud Directory users.
Note: An export JSON file is created only when the export request is successful. If the request fails, to lower your vulnerability risk, the data that is gathered is deleted. The export is automatically deleted after 7 days or the number of days that you specify in the body of the request (in the range of 1 - 30 days). You can choose to manually delete the export by sending a request to the delete API endpoint.
POST /management/v4/{tenantId}/cloud_directory/export/allRequest
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The encryption secret, email address, and expiration information as a JSON object.
{
"encryptionSecret": "f5R3D2aH&4@",
"emailAddress": "test@ibm.com",
"expires": 7
}The email address to which the notification is sent.
Possible values: 3 ≤ length ≤ 254
The encryption secret is a custom string that is used to encrypt and decrypt the exported data. Retain the encryption secret as you need it to use the import all users API. Note: IBM does not store the secret so if the secret is lost, you can't access the exported data.
Possible values: 16 ≤ length ≤ 64
You can specify after how many days the export must expire with an integer in the range of 1 - 30. If you do not specify the expiration information, the export is automatically deleted after 7 days.
Possible values: 1 ≤ value ≤ 30
curl -X POST 'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/export/all' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {IAM_token}' \ --data-raw '{"encryptionSecret" : "encryptionSecret", "emailAddress" : "jdoe@example.com"}'
Response
The export job ID that is returned from the export all users API endpoint.
Possible values: length = 36
Status Code
An export job ID that can be used in the export-status API to query the status of your request is returned.
The tenant ID, encryption secret, or email address is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify permissions.
{ "id": "b72fd036-81b1-4e79-b84f-23c8020f4191" }
Get the export status of all Cloud Directory users
Get the status of the request that was made to export all of your Cloud Directory users from an instance of App ID.
GET /management/v4/{tenantId}/cloud_directory/export/statusRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
Query Parameters
The export job ID that is returned from the export all users API.
Possible values: length = 36
curl -X GET 'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/export/status?id=abc123' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {IAM_token}'
Response
The export job ID that is returned from the export all users API endpoint.
Possible values: length = 36
The status of your export request.
Possible values: [
PENDING,IN_PROGRESS,READY,ERROR,ERROR_DELETED,EXPIRED,SCHEDULED_FOR_DELETION]When the job was requested in UTC (ISO 8601).
When the job started to be processed in UTC (ISO 8601).
When the job completed in UTC (ISO 8601).
When the download is no longer available.
Status Code
The details about the job status, when it was requested, started, completed, and expired are returned as a JSON object.
The tenant ID or export job ID is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify permissions.
{ "id": "b72fd036-81b1-4e79-b84f-23c8020f4191", "status": "READY", "requested": "2021-07-16T19:20:11.000Z", "started": "2021-07-16T19:21:30.000Z", "completed": "2021-07-16T19:22:45.000Z", "expires": "2021-07-23T19:20:11.000Z" }
Download exported file of all Cloud Directory users
Download a JSON file of all of the Cloud Directory users from an instance of App ID. Before you can download the file, you must generate it by running the export all users API endpoint.
Note: You must regenerate the exported file if the deadline you configured before you ran the export request (or the 7-day default deadline) is expired. You can choose to manually delete the export by sending a request to the delete endpoint.
GET /management/v4/{tenantId}/cloud_directory/export/downloadRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
Query Parameters
The export job ID that is returned from the export all users API.
Possible values: length = 36
curl -X GET 'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/export/download?id=abc123' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {IAM_token}'
Response
The full list of users in your Cloud Directory and their profiles as a JSON object.
- users
The user's identity.
The hashed password.
The algorithm that is used to hash the password.
The user's profile.
- profile
The user's profile attributes.
The user's role.
Status Code
The full list of users in your Cloud Directory and their profiles is returned as a JSON attachment.
The file that contains the list of users in your Cloud Directory and their profiles was not found.
The tenant ID or export job ID is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify permissions.
[ { "scimUser": { "originalId": "e403878c-3ab5-4e99-8953-bb57b05387d8", "name": { "givenName": "Jane", "familyName": "Doe", "formatted": "Jane Doe" }, "displayName": "Jane Doe", "active": true, "emails": [ { "value": "user09857654@mail.com", "primary": true } ] }, "passwordHash": "xveImwVxuO7jxRQlRveKgBXD4WoAG0aIHVTY0GLSuTQbfTIsTNy753LFE9kdReAnBTIbSOeQ69UKJdnIxBZZkm9oWf8wsmwWeZwU9njZDDdhxzJWfvAv6Y/XjAqvNdWvJfV3Tag/zwQtKaET6Sc2gSbFL8L1X1wRR/msNA+NSfg=", "passwordHashAlg": "PBKDF2WithHmacSHA512", "profile": { "attributes": { "points": 100 } }, "roles": [] }, { "scimUser": { "originalId": "66ad3522-2251-4531-abff-3e3aad66b650", "userName": "myUserName", "name": { "givenName": "John", "familyName": "Doe", "formatted": "John Doe" }, "displayName": "John Doe", "active": true, "emails": [ { "value": "user0987654@mail.com", "primary": true } ] }, "passwordHash": "YKmBYObTprREAKqjl8F94ofE5lF5lr7Zuc/eJ0Sylvx6IOgI97M56n16U0aGWqBVTu2/P8xayrr6utoH/Uok5v/3Ct9jddXlxhkA1odqgQslJdXiCcBHn/49xU9iejCu6p3PL/81vBfcBGxTll2xeHzF+0qF4rxzn91H6TuNH4o=", "passwordHashAlg": "PBKDF2WithHmacSHA512", "profile": { "attributes": { "points": 150 } }, "roles": [ "adult", "child" ] } ]
Delete exported file of all Cloud Directory users
Submit a request to delete the JSON file that contains the exported list of Cloud Directory users from a specific instance of App ID.
When you send the request, the file is scheduled for deletion. You can track the status of your request as needed. When the file is successfully deleted, the status of your request changes from scheduled_for_deletion to expired.
DELETE /management/v4/{tenantId}/cloud_directory/export/downloadRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
Query Parameters
The export job ID that is returned from the export all users API.
Possible values: length = 36
curl -X DELETE 'https://{region}.appid.cloud.ibm.com/management/v4/{tenant-ID}/export/download?id=abc123' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {IAM_token}'
Response
Status Code
All content that is associated with the export job ID {{id}} was successfully deleted.
The tenant ID or export job ID is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify permissions.
No content found to delete.
No Sample Response
Import all Cloud Directory users
Import all of the Cloud Directory users that are associated with a specific instance of App ID. You can track the status of your request as needed.
When the import is ready or if the request fails, an email is sent to the email address provided.
POST /management/v4/{tenantId}/cloud_directory/import/allRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
Query Parameters
The encryption secret is a custom string that is used to encrypt and decrypt the exported data. Retain the encryption secret as you need it to use the import all users API. Note: IBM does not store the secret so if the secret is lost, you can't access the exported data.
The email address to which the notification is sent.
Form Parameters
The output from the export-download endpoint.
curl -X POST 'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/import/all' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {IAM_token}' \ --form 'file=@"User/desktop/user_list.json"' \ --form 'encryption_secret="encryptionSecret123"' \ --form 'emailAddress="jdoe@example.com"'
Response
The export job ID that is returned from the export all users API endpoint.
Possible values: length = 36
Status Code
'An import ID that can be used to get the import status of your request is returned.'
The tenant ID, encryption secret, email address, or request body is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify permissions.
{ "id": "b72fd036-81b1-4e79-b84f-23c8020f4191" }
Get the import status of all Cloud Directory users
Get the status of the request to import all Cloud Directory users that are associated with the specific import job ID and tenant ID.
GET /management/v4/{tenantId}/cloud_directory/import/statusRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
Query Parameters
The import job ID that is returned from the import all users API.
Possible values: length = 36
curl -X GET 'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/import/status?id=abc123' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {IAM_token}'
Response
The import job ID.
Possible values: length = 36
The status of your import request.
Possible values: [
PENDING_UPLOAD,PENDING,IN_PROGRESS,COMPLETE,ERROR,ERROR_DELETED,EXPIRED,COMPLETE_WITH_FAILURES,SCHEDULED_FOR_DELETION]When the job was requested in UTC (ISO 8601)
When the job started to be processed in UTC (ISO 8601)
When the job completed in UTC (ISO 8601)
When the download will no longer be available
The result of the import
Status Code
Details about the job status, when it was requested, started, and completed are returned as a JSON object.
The tenant ID or import job ID is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify permissions.
{ "id": "b72fd036-81b1-4e79-b84f-23c8020f4191", "status": "READY", "requested": "2021-07-16T19:20:11.000Z", "started": "2021-07-16T19:21:30.000Z", "completed": "2021-07-16T19:22:45.000Z", "expires": "2021-07-23T19:20:11.000Z", "result": { "added": 30, "failed": 1, "failReasons": [ { "originalId": "773f85b4-72f4-480d-aca8-755f517c4508", "id": "664f85b4-72f4-480d-aca8-755f517c4909", "email": "user@mail.com", "userName": "myUserName", "error": { "message": "The email that you entered is already taken.", "status": 409 } } ] } }
Get Cloud Directory users
Get the list of Cloud Directory users. Learn more.
GET /management/v4/{tenantId}/cloud_directory/UsersRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
Query Parameters
The first result in a set list of results.
The maximum number of results per page.
Possible values: 0 ≤ value ≤ 100
The users by identity field.
curl -X 'GET'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/cloud_directory/Users' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
The list of Cloud Directory users.
The number of results.
The number of items per page.
The status of the user profile.
The time limit until which the user is locked out of their account.
Example:
1834879417592
Status Code
The Cloud Directory users data is returned as a JSON object. Find more information about full user data here{: external}.
The tenant ID is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify permissions.
{ "totalResults": 2, "itemsPerPage": 2, "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ], "Resources": [ { "displayName": "John Doe", "active": true, "emails": [ { "value": "johndoe@example.com", "primary": true } ], "meta": { "created": "2019-05-29T12:45:30.671Z", "lastModified": "2019-05-29T12:45:30.671Z", "resourceType": "User" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "name": { "givenName": "John", "familyName": "Doe", "formatted": "John Doe" }, "id": "66ad3522-2251-4531-abff-3e3aad66b650" }, { "displayName": "Jane Doe", "active": true, "emails": [ { "value": "jane@example.com", "primary": true } ], "meta": { "created": "2019-05-29T12:47:20.509Z", "lastModified": "2019-05-29T12:47:20.509Z", "resourceType": "User" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "name": { "givenName": "Jane", "familyName": "Doe", "formatted": "Jane Doe" }, "id": "e403878c-3ab5-4e99-8953-bb57b05387d8" } ] }
Create a Cloud Directory user
Create a record for Cloud Directory (no verification email is sent, and no profile is created). To create a new Cloud Directory user, use the Sign up API. Learn more.
POST /management/v4/{tenantId}/cloud_directory/UsersRequest
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The stored Cloud Directory user data.
The email details.
The password.
Example:
userPasswordThe user's username.
Possible values: length ≤ 200
Example:
myUserNameThe status of the request. Accepted values "PENDING" or "CONFIRMED".
Example:
PENDING
curl -X 'POST'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/cloud_directory/Users' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}' -H 'Content-Type: application/json' -d '{ "active":true, "emails": [ { "value":"jdoe@example.com", "primary":true, } ] "userName":"jdoe", "password":"password123", } '
Response
Status Code
The new Cloud Directory user data is returned as a JSON object. Full user data can be found here{: external}.
The tenant ID or request body is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
The email exists in the directory. You can try searching for the user or registering a different email.
{ "displayName": "John Doe", "active": true, "emails": [ { "value": "johndoe@example.com", "primary": true } ], "meta": { "created": "2019-05-29T12:45:30.671Z", "lastModified": "2019-05-29T12:45:30.671Z", "resourceType": "User" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "name": { "givenName": "John", "familyName": "Doe", "formatted": "John Doe" }, "id": "66ad3522-2251-4531-abff-3e3aad66b650" }
Get a Cloud Directory user
Get the requested Cloud Directory user object. Learn more.
GET /management/v4/{tenantId}/cloud_directory/Users/{userId}Request
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The ID assigned to a user when they sign in by using Cloud Directory. You can find the userId by navigating to App ID > Cloud Directory > Users in the UI and clicking the user's email.
curl -X 'GET'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/cloud_directory/Users/{userId}' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
Status Code
The updated Cloud Directory user data is returned as a JSON object. Full user data can be found here{: external}.
The tenant ID or user ID is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify permissions.
The Cloud Directory user was not found.
{ "displayName": "John Doe", "active": true, "emails": [ { "value": "johndoe@example.com", "primary": true } ], "meta": { "created": "2019-05-29T12:45:30.671Z", "lastModified": "2019-05-29T12:45:30.671Z", "resourceType": "User" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "name": { "givenName": "John", "familyName": "Doe", "formatted": "John Doe" }, "id": "66ad3522-2251-4531-abff-3e3aad66b650" }
Update a Cloud Directory user
Update an existing Cloud Directory user. Learn more.
PUT /management/v4/{tenantId}/cloud_directory/Users/{userId}Request
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The ID assigned to a user when they sign in by using Cloud Directory. You can find the userId by navigating to App ID > Cloud Directory > Users in the UI and clicking the user's email.
The Cloud Directory user data.
The email details.
The user's username.
Possible values: length ≤ 200
Example:
myUserNameThe password.
Example:
userPasswordThe status of the user. This parameter determines whether the user account is active or not.
If both parameters are passed (active: false and lockedUntil) - the user account is locked until the time that is configured.
If only (active: false) is passed, the user account is locked forever (or until it changes again).
The number of milliseconds after which the user account is locked.
If both parameters are passed (active: false and lockedUntil) - the user account is locked until the time that is configured.
If only (active: false) is passed, the user account is locked forever (or until it changes again).
Example:
1834879417592
curl -X 'PUT'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/cloud_directory/Users/{userId}' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}' -H 'Content-Type: application/json' -d '{ "active":false, "lockedUntil":1834879417592, "emails": [ { "value":"jdoe@example.com", "primary":true, } ] "userName":"jdoe", "password":"password123", } '
Response
Status Code
The updated Cloud Directory user data is returned as a JSON object. Full user data can be found here{: external}.
The tenant ID or request body is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
The Cloud Directory user was not found.
The email exists in the directory. You can try searching for the user or registering a different email.
{ "displayName": "John Doe", "active": true, "emails": [ { "value": "johndoe@example.com", "primary": true } ], "meta": { "created": "2019-05-29T12:45:30.671Z", "lastModified": "2019-05-29T12:45:30.671Z", "resourceType": "User" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "name": { "givenName": "John", "familyName": "Doe", "formatted": "John Doe" }, "id": "66ad3522-2251-4531-abff-3e3aad66b650" }
Delete a Cloud Directory user
Delete an existing Cloud Directory record (without removing the associated profile). Learn more. To remove a Cloud Directory user, use the Delete Cloud Directory user and profile API. Note: This action cannot be undone.
DELETE /management/v4/{tenantId}/cloud_directory/Users/{userId}Request
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The ID assigned to a user when they sign in by using Cloud Directory. You can find the userId by navigating to App ID > Cloud Directory > Users in the UI and clicking the user's email.
curl -X 'DELETE'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/cloud_directory/Users/{userId}' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
Status Code
The user was deleted from the Cloud Directory.
The tenant ID is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify permissions.
The Cloud Directory user was not found.
No Sample Response
Invalidate all SSO sessions
Invalidate all the user's SSO sessions. Learn more.
POST /management/v4/{tenantId}/cloud_directory/Users/{userId}/sso/logoutRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The ID assigned to a user when they sign in by using Cloud Directory. You can find the userId by navigating to App ID > Cloud Directory > Users in the UI and clicking the user's email.
curl -X 'POST'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/cloud_directory/Users/{userId}/sso/logout' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token} -d ''
Response
Status Code
No content. All SSO sessions of the user were invalidated.
The tenant ID is invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
The Cloud Directory user was not found.
No Sample Response
Export Cloud Directory users
Export Cloud Directory users with their profile attributes and hashed passwords.
Note: This endpoint is reserved for smaller exports of approximately less than 16,000 users. To export all of your Cloud Directory users who are associated with a specific tenant ID, use the export all users API endpoint. Learn more.
GET /management/v4/{tenantId}/cloud_directory/exportRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
Query Parameters
The encryption secret is a custom string that is used to encrypt and decrypt the exported data. Retain the encryption secret as you need it to use the import all users API. Note: IBM does not store the secret so if the secret is lost, you can't access the exported data.
The first result in a set list of results.
The maximum number of results per page. Limit to 50 users per request.
Possible values: value ≥ 0
curl -X 'GET'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/cloud_directory/export?encryption_secret=encryption123 -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
The list of Cloud Directory users with their profile attributes and hashed passwords.
The status of the user profile.
The number of milliseconds of inactivity after which users will be locked out of their account.
Possible values: number of items ≤ 50
Example:
1834879417592
Status Code
A list of the users in your Cloud Directory and their profiles is returned as a JSON object. You can see up to 50 users per request.'
The tenant ID or user ID is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify permissions.
The Cloud Directory user was not found.
{ "itemsPerPage": 2, "totalResults": 2, "users": [ { "scimUser": { "originalId": "e403878c-3ab5-4e99-8953-bb57b05387d8", "name": { "givenName": "Jane", "familyName": "Doe", "formatted": "Jane Doe" }, "displayName": "Jane Doe", "active": true, "emails": [ { "value": "user09857654@mail.com", "primary": true } ] }, "passwordHash": "xveImwVxuO7jxRQlRveKgBXD4WoAG0aIHVTY0GLSuTQbfTIsTNy753LFE9kdReAnBTIbSOeQ69UKJdnIxBZZkm9oWf8wsmwWeZwU9njZDDdhxzJWfvAv6Y/XjAqvNdWvJfV3Tag/zwQtKaET6Sc2gSbFL8L1X1wRR/msNA+NSfg=", "passwordHashAlg": "PBKDF2WithHmacSHA512", "profile": { "attributes": { "points": 100 } }, "roles": [] }, { "scimUser": { "originalId": "66ad3522-2251-4531-abff-3e3aad66b650", "userName": "myUserName", "name": { "givenName": "John", "familyName": "Doe", "formatted": "John Doe" }, "displayName": "John Doe", "active": true, "emails": [ { "value": "user0987654@mail.com", "primary": true } ] }, "passwordHash": "YKmBYObTprREAKqjl8F94ofE5lF5lr7Zuc/eJ0Sylvx6IOgI97M56n16U0aGWqBVTu2/P8xayrr6utoH/Uok5v/3Ct9jddXlxhkA1odqgQslJdXiCcBHn/49xU9iejCu6p3PL/81vBfcBGxTll2xeHzF+0qF4rxzn91H6TuNH4o=", "passwordHashAlg": "PBKDF2WithHmacSHA512", "profile": { "attributes": { "points": 150 } }, "roles": [ "adult", "child" ] } ] }
Import Cloud Directory users
Import Cloud Directory users list that was exported by using the export endpoint. The format for import is the same format in which the users are exported from the initial instance. You can add up to only 50 users per request. To add all of your users through a single request, use the import all users API endpoint. Learn more.
POST /management/v4/{tenantId}/cloud_directory/importRequest
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
Query Parameters
The encryption secret is a custom string that is used to encrypt and decrypt the exported data. Retain the encryption secret as you need it to use the import all users API. Note: IBM does not store the secret so if the secret is lost, you can't access the exported data.
The exported Cloud Directory users as a JSON object (as returned by the export endpoint).
{
"itemsPerPage": 2,
"totalResults": 2,
"users": [
{
"scimUser": {
"originalId": "e403878c-3ab5-4e99-8953-bb57b05387d8",
"name": {
"givenName": "Jane",
"familyName": "Doe",
"formatted": "Jane Doe"
},
"displayName": "Jane Doe",
"active": true,
"emails": [
{
"value": "user09857654@mail.com",
"primary": true
}
]
},
"passwordHash": "xveImwVxuO7jxRQlRveKgBXD4WoAG0aIHVTY0GLSuTQbfTIsTNy753LFE9kdReAnBTIbSOeQ69UKJdnIxBZZkm9oWf8wsmwWeZwU9njZDDdhxzJWfvAv6Y/XjAqvNdWvJfV3Tag/zwQtKaET6Sc2gSbFL8L1X1wRR/msNA+NSfg=",
"passwordHashAlg": "PBKDF2WithHmacSHA512",
"profile": {
"attributes": {
"points": 100
}
},
"roles": []
},
{
"scimUser": {
"originalId": "66ad3522-2251-4531-abff-3e3aad66b650",
"userName": "myUserName",
"name": {
"givenName": "John",
"familyName": "Doe",
"formatted": "John Doe"
},
"displayName": "John Doe",
"active": true,
"emails": [
{
"value": "user0987654@mail.com",
"primary": true
}
]
},
"passwordHash": "YKmBYObTprREAKqjl8F94ofE5lF5lr7Zuc/eJ0Sylvx6IOgI97M56n16U0aGWqBVTu2/P8xayrr6utoH/Uok5v/3Ct9jddXlxhkA1odqgQslJdXiCcBHn/49xU9iejCu6p3PL/81vBfcBGxTll2xeHzF+0qF4rxzn91H6TuNH4o=",
"passwordHashAlg": "PBKDF2WithHmacSHA512",
"profile": {
"attributes": {
"points": 150
}
},
"roles": [
"adult",
"child"
]
}
]
}The list of Cloud Directory users with their profile attributes and hashed passwords.
The status of the user profile.
The number of milliseconds of inactivity after which users will be locked out of their account.
Possible values: number of items ≤ 50
Example:
1834879417592
curl -X 'POST'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/cloud_directory/import?encryption_secret=encryption123' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}' -H 'Content-Type: application/json' -d '{ "itemsPerPage": 2, "totalResults": 2, "users": [ { "scimUser": { "originalId": "e403878c-3ab5bb57b05387d8", "name": { "givenName": "Jane", "familyName": "Doe", "formatted": "Jane Doe" }, "displayName": "Jane Doe", "active": true, "emails": [ { "value": "user09857654@mail.com", "primary": true } ] }, "passwordHash": "xveImwVxuO7jxRQlRveKg", "passwordHashAlg": "PBKDF2WithHmacSHA512", "profile": { "attributes": { "points": 100 } }, "roles": [] }, { "scimUser": { "originalId": "66ad35223e3aad66b650", "userName": "myUserName", "name": { "givenName": "John", "familyName": "Doe", "formatted": "John Doe" }, "displayName": "John Doe", "active": true, "emails": [ { "value": "user0987654@mail.com", "primary": true } ] }, "passwordHash": "YKmBYObTprREAKqjl8F", "passwordHashAlg": "PBKDF2WithHmacSHA512", "profile": { "attributes": { "points": 150 } }, "roles": [ "adult", "child" ] } ] }'
Response
The number of profiles that are imported successfully.
The status of the request.
The number of milliseconds of inactivity after which users will be locked of their accounts.
Example:
1834879417592The number of users that failed to import.
The reasons why users failed to import.
- failReasons
The original ID.
The ID.
The email.
THe username.
The error message.
Status Code
Import Cloud Directory users from another instance of App ID. The format for import is the same format in which the users are exported from the initial instance. You can add up to 50 users per request.
The tenant ID or user ID is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify permissions.
The Cloud Directory user was not found.
{ "added": 30, "failed": 1, "failReasons": [ { "originalId": "773f85b4-72f4-480d-aca8-755f517c4508", "id": "664f85b4-72f4-480d-aca8-755f517c4909", "email": "user@mail.com", "userName": "myUserName", "error": { "message": "The email that you entered is already taken.", "status": 409 } } ] }
Get Cloud Directory SCIM and Attributes
Get the Cloud Directory user System for Cross-domain Identity Management (SCIM) and the profile related to it. Learn more.
GET /management/v4/{tenantId}/cloud_directory/{userId}/userinfoRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The ID assigned to a user when they sign in by using Cloud Directory. You can find the userId by navigating to App ID > Cloud Directory > Users in the UI and clicking the user's email.
curl -X 'GET' \'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/cloud_directory/{userId}/userinfo -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
The request's ID.
The details of the user's identity.
- identities
The identity provider.
The ID.
The user information from the identity provider.
Examples:{ "displayName": "John Doe", "active": true, "emails": [ { "value": "johndoe@example.com", "primary": true } ], "meta": { "created": "2019-05-29T12:45:30.671Z", "lastModified": "2019-05-29T12:45:30.671Z", "resourceType": "User" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "name": { "givenName": "John", "familyName": "Doe", "formatted": "John Doe" }, "id": "66ad3522-2251-4531-abff-3e3aad66b650" }
The user's profile attributes.
Status Code
The user's data is returned as a JSON object.
Invalid tenant ID/user ID.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify permissions.
The user is not found.
{ "sub": "122e1dd7-2a7f-18fb-b8ed-ed78c3f92c2b", "identities": [ { "provider": "cloud_directory", "id": "773f85b4-72f4-480d-aca8-755f517c4508", "idpUserInfo": { "displayName": "John Doe", "active": true, "emails": [ { "value": "johndoe@example.com", "primary": true } ], "meta": { "created": "2019-05-29T12:45:30.671Z", "lastModified": "2019-05-29T12:45:30.671Z", "resourceType": "User" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "name": { "givenName": "John", "familyName": "Doe", "formatted": "John Doe" }, "id": "66ad3522-2251-4531-abff-3e3aad66b650" } } ], "attributes": { "points": 150 } }
Delete a TOTP registration
Delete a user's time-based one-time passcode (TOTP) registration. If a user never used TOTP, this operation has no effect.
DELETE /management/v4/{tenantId}/cloud_directory/Users/{userId}/mfa/totpRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The ID assigned to a user when they sign in by using Cloud Directory. You can find the userId by navigating to App ID > Cloud Directory > Users in the UI and clicking the user's email.
curl -X 'DELETE' \'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/cloud_directory/Users/{userId}/mfa/totp -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
Status Code
The TOTP registration was deleted successfully.
The tenant ID or user ID is missing or invalid.
The request is unauthorized by the platform. To be authorized, an IAM token with the valid permissions must be provided in the authorization header of your request.
You are not authorized to complete this operation. Contact the service owner or admin to verify your permissions.
The user was not found.
Returned because of an internal server error.
No Sample Response
View all roles
Obtain a list of the roles that are associated with your registered application.
GET /management/v4/{tenantId}/rolesRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
curl -X 'GET'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/roles' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
A list of the roles that are associated with your registered application.
- roles
The role ID.
Example:
12345678-1234-1234-1234-123456789012The role name.
Example:
adultThe role description.
Example:
No movie restrictions in place.The access data.
- access
The application ID.
Example:
de33d272-f8a7-4406-8fe8-ab28fd457be5The scopes.
Examples:[ "cartoons", "horror", "animated" ]
Status Code
The roles for the registered application are returned as a JSON object.
The tenant ID or user ID is missing or invalid.
The request is unauthorized. Be sure that you pass a valid IAM token in the authorization header of your request.
You have insufficient permissions. Contact your administrator to verify your permissions.
No Sample Response
Request
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
A JSON object that defines the role that you want to create. For example, the associated model is one that you might see in a video streaming service.
The role name.
Possible values: length ≤ 50
Example:
childThe access data.
- access
The application ID.
Example:
de33d272-f8a7-4406-8fe8-ab28fd457be5The scopes.
Examples:[ "cartoons" ]
The role description.
Possible values: length ≤ 100
Example:
Limits the available movie options to films that might be more appropriate for younger viewers.
curl -X 'POST'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/users/{id}/roles' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}' -H 'Content-Type: application/json' -d '{ "name":"child", "description":"Limits the available movie options to those that might be more appropriate for younger viewers.", "access": [ { "application_id":"<enter_application_id>", "scopes": [ "cartoons" ] } ] } '
Response
The role ID.
Example:
12345678-1234-1234-1234-123456789013The role name.
Example:
childThe access data.
- access
THe application ID.
Example:
de33d272-f8a7-4406-8fe8-ab28fd457be5The scopes.
Examples:[ "cartoons" ]
The description.
Example:
Limits the available movie options to films that might be more appropriate for younger viewers.
Status Code
The role for the registered application is created and returned as a JSON object.
The payload is missing or invalid.
The request is unauthorized. Be sure that you pass a valid IAM token in the authorization header of your request.
You have insufficient permissions. Contact your administrator to verify your permissions.
The role exists. Choose a new name or update your existing role.
No Sample Response
View a specific role
By using the role ID, obtain the information for a specific role that is associated with a registered application.
GET /management/v4/{tenantId}/roles/{roleId}Request
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The role identifier. You can find the roleId by navigating to App ID > Profiles and roles > Roles in the UI.
curl -X 'GET'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/roles/{roleId}' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
The role ID.
Example:
12345678-1234-1234-1234-123456789012The role name.
Example:
adultThe role description.
Example:
No movie restrictions in place.The access data.
- access
The application ID.
Example:
de33d272-f8a7-4406-8fe8-ab28fd457be5The scopes.
Examples:[ "cartoons", "horror", "animated" ]
Status Code
The data that is associated with the role is returned as a JSON object.
The tenant ID or user ID is missing or invalid.
The request is unauthorized. Be sure that you pass a valid IAM token in the authorization header of your request.
You have insufficient permissions. Contact your administrator to verify your permissions.
The role was not found. Verify your role ID by listing all of the roles that are associated with your application.
No Sample Response
Request
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The role identifier. You can find the roleId by navigating to App ID > Profiles and roles > Roles in the UI.
A JSON object that defines the role that you want to update. Continuing the previous example, you can see that an extra scope is added to the payload.
The role name.
Possible values: length ≤ 50
Example:
childThe access data.
- access
The application ID.
Example:
de33d272-f8a7-4406-8fe8-ab28fd457be5The scopes.
Examples:[ "cartoons", "animated" ]
The role description.
Possible values: length ≤ 100
Example:
Limits the available movie options to films that might be more appropriate for younger viewers.
curl -X 'PUT'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/users/{id}/roles/{roleId}' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}' -H 'Content-Type: application/json' -d '{ "name":"child", "description":"Limits the available movie options to those that might be more appropriate for younger viewers.", "access": [ { "application_id":"<enter_application_id>", "scopes": [ "cartoons", "animated" ] } ] } '
Response
Example:
12345678-1234-1234-1234-123456789013The name.
Example:
childThe access data.
- access
The application ID.
Example:
de33d272-f8a7-4406-8fe8-ab28fd457be5The scopes.
Examples:[ "cartoons", "animated" ]
The description.
Example:
Limits the available movie options to films that might be more appropriate for younger viewers.
Status Code
The role is updated and the data that is associated with the role is returned as a JSON object.
The payload is missing or invalid.
The request is unauthorized. Be sure that you pass a valid IAM token in the authorization header of your request.
You have insufficient permissions. Contact your administrator to verify your permissions.
The role was not found. Verify your role ID by listing all of the roles that are associated with your application.
No Sample Response
Request
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The role identifier. You can find the roleId by navigating to App ID > Profiles and roles > Roles in the UI.
curl -X 'DELETE'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/roles/{roleId}' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Get applications
View all applications registered with the App ID Instance.
GET /management/v4/{tenantId}/applicationsRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
curl -X 'GET'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/applications' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
The applications registered with the App ID instance.
- applications
The client ID.
The tenant ID.
The secret.
The application name.
The oauth server URL.
The application type.
Status Code
A list of all the applications that are registered with the App ID tenant ID is returned as a JSON object.
The tenant ID is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify permissions.
{ "clientId": "111c22c3-38ea-4de8-b5d4-338744d83b0f", "tenantId": "39a37f57-a227-4bfe-a044-93b6e6060b61", "secret": "ZmE5ZDQ5ODctMmU1ZS00OGRiLWExZDMtZTA2MjkyZTc4MDB1", "name": "IBMCloudApp", "oAuthServerUrl": "https://us-south.appid.cloud.ibm.com/oauth/v4/39a37f57-a227-4bfe-a044-93b6e6060b61", "type": "regularwebapp" }
Create application
Register a new application with the App ID instance.
POST /management/v4/{tenantId}/applicationsRequest
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The application registration payload. Application name cannot exceed 50 characters.
{
"name": "App1",
"type": "regularwebapp"
}The application name to be registered. Application name cannot exceed 50 characters.
Possible values: 1 ≤ length ≤ 50
The type of application to be registered. Allowed types are regularwebapp and singlepageapp.
curl -X 'POST'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/applications' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}' -H 'Content-Type: application/json' -d '{ "name": "App1-test", "type": "regularwebapp" }'
Response
The applications registered with the App ID instance.
- applications
The client ID.
The tenant ID.
The secret.
The application name.
The oauth server URL.
The application type.
Status Code
The new registered application data is returned as a JSON object.
The tenant ID or request body is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
Returned because of an internal server error.
{ "clientId": "111c22c3-38ea-4de8-b5d4-338744d83b0f", "tenantId": "39a37f57-a227-4bfe-a044-93b6e6060b61", "secret": "ZmE5ZDQ5ODctMmU1ZS00OGRiLWExZDMtZTA2MjkyZTc4MDB1", "name": "IBMCloudApp", "oAuthServerUrl": "https://us-south.appid.cloud.ibm.com/oauth/v4/39a37f57-a227-4bfe-a044-93b6e6060b61", "type": "regularwebapp" }
Get application
Get a specific application registered with the App ID Instance.
GET /management/v4/{tenantId}/applications/{clientId}Request
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The application client ID. The client ID can be found in the application credentials or service credentials. You might need to create a service credential if one does not exist.
curl -X 'GET'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/applications/{clientId}' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
The applications registered with the App ID instance.
- applications
The client ID.
The tenant ID.
The secret.
The application name.
The oauth server URL.
The application type.
Status Code
A specific application that is registered with the App ID tenant ID is returned as a JSON object.
The tenant ID is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify permissions.
{ "clientId": "111c22c3-38ea-4de8-b5d4-338744d83b0f", "tenantId": "39a37f57-a227-4bfe-a044-93b6e6060b61", "secret": "ZmE5ZDQ5ODctMmU1ZS00OGRiLWExZDMtZTA2MjkyZTc4MDB1", "name": "IBMCloudApp", "oAuthServerUrl": "https://us-south.appid.cloud.ibm.com/oauth/v4/39a37f57-a227-4bfe-a044-93b6e6060b61", "type": "regularwebapp" }
Update application
Update an application registered with the App ID instance.
PUT /management/v4/{tenantId}/applications/{clientId}Request
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The application client ID. The client ID can be found in the application credentials or service credentials. You might need to create a service credential if one does not exist.
The application registration payload. Application name cannot exceed 50 characters.
{
"name": "App1"
}The application name to be updated. Application name cannot exceed 50 characters.
Possible values: 1 ≤ length ≤ 50
curl -X 'PUT'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/applications/{clientId}' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}' -H 'Content-Type: application/json' -d '{ "name": "App1-test" }'
Response
The applications registered with the App ID instance.
- applications
The client ID.
The tenant ID.
The secret.
The application name.
The oauth server URL.
The application type.
Status Code
The updated application data is returned as a JSON object.
The tenant ID or request body is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
The application was not be found.
Returned because of an internal server error.
{ "clientId": "111c22c3-38ea-4de8-b5d4-338744d83b0f", "tenantId": "39a37f57-a227-4bfe-a044-93b6e6060b61", "secret": "ZmE5ZDQ5ODctMmU1ZS00OGRiLWExZDMtZTA2MjkyZTc4MDB1", "name": "IBMCloudApp", "oAuthServerUrl": "https://us-south.appid.cloud.ibm.com/oauth/v4/39a37f57-a227-4bfe-a044-93b6e6060b61", "type": "regularwebapp" }
Delete application
Delete an application registered with the App ID instance. Note: This action cannot be undone.
DELETE /management/v4/{tenantId}/applications/{clientId}Request
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The application client ID. The client ID can be found in the application credentials or service credentials. You might need to create a service credential if one does not exist.
curl -X 'DELETE' \'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/applications/{clientId}' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
Status Code
The application was deleted.
The tenant ID is missing or invalid.
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
The user has insufficient permissions. Contact the service owner or admin to verify permissions.
The application was not found.
No Sample Response
Get application scopes
View the defined scopes for an application that is registered with an App ID instance.
GET /management/v4/{tenantId}/applications/{clientId}/scopesRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The application client ID. The client ID can be found in the application credentials or service credentials. You might need to create a service credential if one does not exist.
curl -X 'GET' \'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/applications/{clientId}/scopes' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
The scopes.
Possible values: length ≤ 50
Examples:[ "cartoons", "horror", "animated" ]
Status Code
The scopes for the registered application are returned as a JSON object.
The tenant ID or client ID is missing or invalid.
The request is unauthorized. Be sure that you pass a valid IAM token in the authorization header of your request.
You have insufficient permissions. Contact your administrator to verify your permissions.
No Sample Response
Add application scope
Update the scopes for a registered application. Learn more. Important: Removing a scope from an array deletes it from any roles that it is associated with and the action cannot be undone.
PUT /management/v4/{tenantId}/applications/{clientId}/scopesRequest
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The application client ID. The client ID can be found in the application credentials or service credentials. You might need to create a service credential if one does not exist.
The scopes.
Possible values: number of items ≤ 50, length ≤ 20
Examples:[ "cartoons", "horror", "animated" ]
curl -X 'PUT' \'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/applications/{clientId}/scopes' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}' -H 'Content-Type: application/json' -d '{ "scopes": [ "cartoons", "horror", "animated" ] }'
Response
The scopes.
Possible values: length ≤ 50
Examples:[ "cartoons", "horror", "animated" ]
Status Code
The updated scopes for the registered application are returned as a JSON object.
The tenant ID, client ID, or request body is missing or invalid.
The request is unauthorized. Be sure that you pass a valid IAM token in the authorization header of your request.
You have insufficient permissions. Contact your administrator to verify your permissions.
The application cannot be found.
No Sample Response
Get application roles
View the defined roles for an application that is registered with an App ID instance.
GET /management/v4/{tenantId}/applications/{clientId}/rolesRequest
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The application client ID. The client ID can be found in the application credentials or service credentials. You might need to create a service credential if one does not exist.
curl -X 'GET'\'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/applications/{clientId}/roles' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}'
Response
The user's roles.
- roles
The role ID.
Example:
111c22c3-38ea-4de8-b5d4-338744d83b0fThe role name.
Example:
adult
Status Code
The roles for the registered application are returned as a JSON object.
The tenant ID or client ID is missing or invalid.
The request is unauthorized. Be sure that you pass a valid IAM token in the authorization header of your request.
You have insufficient permissions. Contact your administrator to verify your permissions.
No Sample Response
Add application role
Update the roles for a registered application.
PUT /management/v4/{tenantId}/applications/{clientId}/rolesRequest
Custom Headers
Allowable values: [
application/json,application/x-www-form-urlencoded,multipart/form-data]
Path Parameters
The service tenant ID. The tenant ID can be found in the service credentials. You can create a service credential if one does not exist.
The application client ID. The client ID can be found in the application credentials or service credentials. You might need to create a service credential if one does not exist.
A JSON array of roles. The Array can have either names or IDs but not both.
The user's roles.
- roles
The role IDs.
Possible values: number of items ≤ 50
curl -X 'PUT' \'https://{region}.appid.cloud.ibm.com/management/v4/{tenant_ID}/applications/{clientId}/roles' -H 'accept: application/json' -H 'Authorization: Bearer {IAM_token}' -H 'Content-Type: application/json' -d '{ "roles": { "ids": [ "cc89a2c33a4d15863f0d" ] } }'
Response
The user's roles.
Possible values: number of items ≤ 50
- roles
The role ID.
Example:
111c22c3-38ea-4de8-b5d4-338744d83b0fThe role name.
Example:
child
Status Code
The role is successfully associated with the application.
The tenant ID, client ID, or request body is missing or invalid.
The request is unauthorized. Be sure that you pass a valid IAM token in the authorization header of your request.
You have insufficient permissions. Contact your administrator to verify your permissions.
The application cannot be found.