Get Facebook IDP configuration

GET /management/v4/{tenantId}/config/idps/facebook

Get the Facebook identity provider configuration. Learn more.

Request

Path Parameters

tenantId

Required *

string

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

Response

200 - The Facebook identity provider configuration is returned as a JSON object, including the status and credentials. Learn more.

isActive

boolean

The status of the configuration.

config

object

The details of the configuration.

400 - The tenant ID or request body is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

500 - Returned because of an internal server error.

Update Facebook IDP configuration

PUT /management/v4/{tenantId}/config/idps/facebook

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.

Request

Request Body

Path Parameters

tenantId

Required *

string

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

Response

200 - The Facebook configuration was updated. The identity provider data is returned as a JSON object.

isActive

boolean

The status of the configuration.

config

object

The details of the configuration.

400 - The tenant ID or request body is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

500 - Returned due to an internal server error.

Get Google IDP configuration

GET /management/v4/{tenantId}/config/idps/google

Get the Google identity provider configuration.

Request

Path Parameters

tenantId

Required *

string

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

Response

200 - The Google identity provider configuration is returned as a JSON object, including the status and credentials. Learn more.

isActive

boolean

The status of the configuration.

config

object

The details of the configuration.

400 - The tenant ID or request body is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

500 - Returned because of an internal server error.

Update Google IDP configuration

PUT /management/v4/{tenantId}/config/idps/google

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.

Request

Request Body

Path Parameters

tenantId

Required *

string

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

Response

200 - The Google configuration was updated. The identity provider data is returned as a JSON object.

isActive

boolean

The status of the configuration.

config

object

The details of the configuration.

400 - The tenant ID or request body is missing or invalid. The tenant ID can be found in the service credentials.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

500 - Returned due to an internal server error.

Get IBMid IDP configuration

GET /management/v4/{tenantId}/config/idps/ibmid

Get the IBMid identity provider configuration.

Request

Path Parameters

tenantId

Required *

string

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

Response

200 - The IBMid identity provider configuration is returned as a JSON object, including the status and credentials.

isActive

boolean

The status of the configuration.

config

object

The details of the configuration.

400 - The tenant ID or request body is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

500 - Returned because of an internal server error.

Update IBMid IDP configuration

PUT /management/v4/{tenantId}/config/idps/ibmid

Configure IBMid to set up a single sign-on experience for your users. Learn more.

Request

Request Body

ibmidConfigParams

The identity provider configuration as a JSON object. If the configuration is not set, IBM default credentials are used.

isActive

Required *

boolean

The status of the configuration.

config

object

The details of the configuration.

idpId

Required *

string

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.

secret

Required *

string

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.

preProd

Required *

boolean

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.

ciBased

boolean

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.

Path Parameters

tenantId

Required *

string

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

Response

200 - The IBMid configuration was updated. The identity provider data is returned as a JSON object.

isActive

boolean

The status of the configuration..

redirectURL

string

The redirect URL.

config

object

The details of the configuration.

400 - The tenant ID or request body is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

500 - Returned because of an internal server error.

Get Custom identity configuration

GET /management/v4/{tenantId}/config/idps/custom

Get the Custom identity configuration.

Request

Path Parameters

tenantId

Required *

string

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

Response

200 - The Custom identity configuration is returned as a JSON object that contains the PEM public key and the isActive status.

isActive

boolean

The status of the configuration.

config

object

The details of the configuration.

400 - The tenant ID or request body is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

500 - Returned because of an internal server error.

Update or change the configuration of the Custom identity.

PUT /management/v4/{tenantId}/config/idps/custom

Configure App ID Custom identity to allow users to sign in by using your own identity provider.

Request

Request Body

customIdPConfigParams

The identity provider configuration as a JSON object.

isActive

Required *

boolean

The status of the configuration.

config

object

The details of the configuration.

publicKey

string

The public key.

Path Parameters

tenantId

Required *

string

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

Response

200 - The Custom identity configuration was updated. The updated configuration is returned as a JSON object.

isActive

boolean

The status of the configuration.

config

object

The details of the configuration.

400 - The tenant ID or request body is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

500 - Returned because of an internal server error.

Get Cloud Directory IDP configuration

GET /management/v4/{tenantId}/config/idps/cloud_directory

Get the Cloud Directory identity provider configuration. Learn more.

Request

Path Parameters

tenantId

Required *

string

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

Response

200 - The Cloud Directory identity provider configuration is returned as a JSON object, including the status and credentials.

isActive

boolean

The status of the configuration.

config

object

The details of the configuration.

400 - The tenant ID or request body is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

500 - Returned because of an internal server error.

Update Cloud Directory IDP configuration

PUT /management/v4/{tenantId}/config/idps/cloud_directory

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.

Request

Request Body

The identity provider configuration as a JSON object. If the configuration is not set, IBM default credentials are used.

isActive

Required *

boolean

The status of the configuration.

config

Required *

cloudDirectoryConfigParams

selfServiceEnabled

Required *

boolean

You allow your users to manage their account from your application.

signupEnabled

boolean

You allow your users to sgn-up to your application.

interactions

Required *

object

The interactions that you allow your users to have with your application.

identityField

string

The identity field.

Path Parameters

tenantId

Required *

string

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

Response

200 - The Cloud Directory configuration was updated. The identity provider data is returned as a JSON object.

isActive

boolean

The status of the configuration.

config

object

The details of the configuration.

400 - The tenant ID or request body is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

500 - Returned because of an internal server error.

Get SAML IDP configuration

GET /management/v4/{tenantId}/config/idps/saml

Get the SAML identity provider configuration, including status and credentials. Learn more.

Request

Path Parameters

tenantId

Required *

string

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

Response

200 - The identity provider configuration for SAML is returned as a JSON object.

isActive

boolean

The status of the configuration.

config

samlConfigParams

The configuration of the SAML IDP.

400 - The tenant ID or request body is missing or invalid. The tenant ID can be found in the service credentials.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

500 - Returned because of an internal server error.

Update SAML IDP configuration

PUT /management/v4/{tenantId}/config/idps/saml

Configure SAML to set up a single sign-on experience for your users. Learn more.

Request

Request Body

The identity provider configuration as a JSON object.

isActive

Required *

boolean

The status of the configuration.

config

samlConfigParams

The configuration of the SAML IDP.

entityID

Required *

string

The entity ID.

signInUrl

Required *

string

The sign-in URL.

certificates

Required *

array

The certificates issued by your SAML identity provider. Certificates are used for signing and validating SAML assertions. Supply the certificate in PEM format.

displayName

string

The display name.

authnContext

object

The authorization context.

signRequest

boolean

The sign request.

encryptResponse

boolean

The encrypted response.

includeScoping

boolean

Scoping is included.

Path Parameters

tenantId

Required *

string

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

Response

200 - The SAML configuration was updated. The idp data is returned as a JSON object.

isActive

boolean

The status of the configuration.

config

samlConfigParams

The configuration of the SAML IDP.

validation_data

object

400 - The tenant ID or request body is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

500 - Returned because of an internal server error.

Get tokens configuration

GET /management/v4/{tenantId}/config/tokens

Get the token configuration. Learn more.

Request

Path Parameters

tenantId

Required *

string

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

Response

200 - Returns a JSON object of the App ID tokens properties.

idTokenClaims

array

The claims of the identity token.

accessTokenClaims

array

The claims of the access token.

access

object

The expiration data of the access token.

refresh

object

The expiration and activity data of the refresh token.

anonymousAccess

object

The expiration and activity data of the anonymous token.

400 - The tenant ID or request body is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

Update tokens configuration

PUT /management/v4/{tenantId}/config/tokens

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.

Request

Request Body

tokensConfigResponse

Set of App ID token objects. 'expires_in' is set in seconds.

idTokenClaims

array

The claims of the identity token.

accessTokenClaims

array

The claims of the access token.

access

object

The expiration data of the access token.

refresh

object

The expiration and activity data of the refresh token.

anonymousAccess

object

The expiration and activity data of the anonymous token.

Path Parameters

tenantId

Required *

string

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

Response

200 - The token configuration was updated.

idTokenClaims

array

The claims of the identity token.

accessTokenClaims

array

The claims of the access token.

access

object

The expiration data of the access token.

refresh

object

The expiration and activity data of the refresh token.

anonymousAccess

object

The expiration and activity data of the anonymous token.

400 - The tenant ID or request body is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

Get redirect URIs

GET /management/v4/{tenantId}/config/redirect_uris

Get the list of the redirect URIs that can be used as callbacks of App ID authentication flow. Learn more.

Request

Path Parameters

tenantId

Required *

string

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

Response

200 - An array of the redirect URIs is returned as a JSON object.

redirectUris

array

The redirect URLs.

400 - The tenant ID parameter is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

Update redirect URIs

PUT /management/v4/{tenantId}/config/redirect_uris

Update the list of the redirect URIs that can be used as callbacks of App ID authentication flow. Learn more.

Request

Request Body

redirectUriConfig

The redirect URIs JSON object. If IBM default credentials are used, the redirect URIs are ignored.

redirectUris

array

The redirect URLs.

trustCloudIAMRedirectUris

boolean

The redirect URLs of trusted cloud IAM.

Path Parameters

tenantId

Required *

string

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

Response

204 - No content. The redirect URIs were updated.

400 - The tenant ID or request body is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

Get user profiles configuration

GET /management/v4/{tenantId}/config/users_profile

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.

Request

Path Parameters

tenantId

Required *

string

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

Response

200 - The current profiles status is returned as a JSON object.

isActive

boolean

The status of the configuration.

400 - The tenant ID is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

Update user profiles configuration

PUT /management/v4/{tenantId}/config/users_profile

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.

Request

Request Body

profiles

The user profile data. It can be enabled or disabled.

isActive

Required *

boolean

The status of the configuration.

Path Parameters

tenantId

Required *

string

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

Response

204 - No content. The user profiles status was updated.

400 - The tenant ID or request body is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

Get widget texts

GET /management/v4/{tenantId}/config/ui/theme_text

Get the theme texts of the App ID login widget. Learn more.

Request

Path Parameters

tenantId

Required *

string

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

Response

200 - The current color configuration is returned as a JSON object.

footnote

string

The footnote.

tabTitle

string

The tab title.

400 - The tenant ID is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

Update widget texts

PUT /management/v4/{tenantId}/config/ui/theme_text

Update the texts of the App ID login widget. Learn more.

Request

Request Body

themeTextConfigParam

The texts of the widget.

tabTitle

string

The tab title.

footnote

string

The footnote.

Path Parameters

tenantId

Required *

string

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

Response

204 - No content, the service login widget header color was updated.

400 - The tenant ID or request body is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

Get widget colors

GET /management/v4/{tenantId}/config/ui/theme_color

Get the colors of the App ID login widget. Learn more.

Request

Path Parameters

tenantId

Required *

string

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

Response

200 - The current color configuration is returned as a JSON object.

headerColor

string

The color of the header.

400 - The tenant ID is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

Update widget colors

PUT /management/v4/{tenantId}/config/ui/theme_color

Update the colors of the App ID login widget. Learn more.

Request

Request Body

themeColorConfigParam

The colors of the widget.

headerColor

string

The color of the header.

Path Parameters

tenantId

Required *

string

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

Response

204 - No content, the service login widget header color was updated.

400 - The tenant ID or request body is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

Delete widget logo

DELETE /management/v4/{tenantId}/config/ui/media

Delete the image file shown in the login widget. Learn more.

Request

Path Parameters

tenantId

Required *

string

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

mediaType

Required *

string

The type of media. You can upload JPG or PNG files.

Response

204 - The logo was deleted.

400 - The tenant ID or file type is missing.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

Get widget logo

GET /management/v4/{tenantId}/config/ui/media

Get the link to the custom logo image of the login widget. Learn more.

Request

Path Parameters

tenantId

Required *

string

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

Response

200 - The current media configurations are returned as a JSON object.

image

string

The custom logo image of the login widget.

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

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

Update widget logo

POST /management/v4/{tenantId}/config/ui/media

Update the image file shown in the login widget. Learn more.

Request

Request Body

Path Parameters

tenantId

Required *

string

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

mediaType

Required *

string

The type of media. You can upload JPG or PNG files.

Response

204 - No content. The service login widget logo was updated.

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

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

Get the SAML metadata

GET /management/v4/{tenantId}/config/saml_metadata

Get the SAML metadata that you need to integrate App ID with a SAML identity provider. Learn more.

Request

Path Parameters

tenantId

Required *

string

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

Response

200 - The metadata for using SAML as a service provider is returned as an xml snippet.

400 - The tenant ID parameter is missing or invalid.

500 - Returned because of an internal server error.

Get an email template

GET /management/v4/{tenantId}/config/cloud_directory/templates/{templateName}/{language}

Get the content of a custom email template or the default template in case it wasn't customized. Learn more.

Request

Path Parameters

tenantId

Required *

string

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.

templateName

Required *

string

The type of email template. The type can be "USER_VERIFICATION", "WELCOME", "PASSWORD_CHANGED", "RESET_PASSWORD" or "MFA_VERIFICATION".

language

Required *

string

Preferred language for resource. Format as described at RFC5646. According to the configured languages codes returned from the `GET /management/v4/{tenantId}/config/ui/languages` API.

Query Parameters

Response

200 - The email template data is returned as a JSON object. If the language template does not exist yet, the english template (en) is returned.

subject

string

The subject of the email.

html_body

string

The HTML body of the email.

base64_encoded_html_body

string

The HTML body of the email encoded in Base64.

plain_text_body

string

The plain text body of the email.

400 - The tenant ID or templateName are missing or invalid or language is not in the app localization configuration.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

Update an email template

PUT /management/v4/{tenantId}/config/cloud_directory/templates/{templateName}/{language}

Update the Cloud Directory email template. Learn more.

Request

Request Body

setTemplate

Email template object. See documentation for available placeholder for each email template.

subject

Required *

string

The subject of the email.

html_body

string

The HTML body of the email.

base64_encoded_html_body

string

The HTML body of the email encoded in Base64.

plain_text_body

string

The plain text body of the email.

Path Parameters

tenantId

Required *

string

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.

templateName

Required *

string

The type of email template. The type can be "USER_VERIFICATION", "WELCOME", "PASSWORD_CHANGED", "RESET_PASSWORD" or "MFA_VERIFICATION".

language

Required *

string

Preferred language for resource. Format as described at RFC5646. According to the configured languages codes returned from the `GET /management/v4/{tenantId}/config/ui/languages` API.

Query Parameters

Response

200 - The email template properties are returned as a JSON object.

subject

string

The subject of the email.

html_body

string

The HTML body of the email.

base64_encoded_html_body

string

The HTML body of the email encoded in Base64.

plain_text_body

string

The plain text body of the email.

201 - The created email template properties are returned as a JSON object.

subject

string

The subject of the email.

html_body

string

The HTML body of the email.

base64_encoded_html_body

string

The HTML body of the email encoded in Base64.

plain_text_body

string

The plain text body of the email.

204 - No content. The template configuration was updated (in case the request Prefer header is return_minimal).

400 - The tenant ID or request body is missing or invalid.

401 - The user is unauthorized.

403 - The user has insufficient permissions.

Delete an email template

DELETE /management/v4/{tenantId}/config/cloud_directory/templates/{templateName}/{language}

Delete the customized email template and reverts to App ID default template. Learn more.

Request

Path Parameters

tenantId

Required *

string

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.

templateName

Required *

string

The type of email template. The type can be "USER_VERIFICATION", "WELCOME", "PASSWORD_CHANGED", "RESET_PASSWORD" or "MFA_VERIFICATION".

language

Required *

string

Preferred language for resource. Format as described at RFC5646. According to the configured languages codes returned from the `GET /management/v4/{tenantId}/config/ui/languages` API.

Query Parameters

Response

204 - The template was deleted.

400 - The tenant ID is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact a service owner or admin to verify permissions.

404 - The template does not exist.

Sign up

POST /management/v4/{tenantId}/cloud_directory/sign_up

Start the sign-up process. Learn more.

Request

Request Body

Path Parameters

tenantId

Required *

string

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

shouldCreateProfile

Required *

boolean

A boolean indication if a profile must be created for the Cloud Directory user.

language

string

Preferred language for resource. Format as described at RFC5646.

Response

201 - The new Cloud Directory user data is returned as a JSON object. Full user data can be found here.

400 - The tenant ID or request body is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

409 - The email address exists.

Get signup confirmation result

POST /management/v4/{tenantId}/cloud_directory/sign_up/confirmation_result

Get the sign-up confirmation result. Learn more.

Request

Request Body

Path Parameters

tenantId

Required *

string

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

Response

200 - The sign-up confirmation result is returned as a JSON object.

success

boolean

The status of the request.

uuid

string

The user's unique ID.

400 - The tenant ID or context is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

404 - The context was not found.

errorCode

string

message

string

Forgot password

POST /management/v4/{tenantId}/cloud_directory/forgot_password

Start the forgot password process. Learn more.

Request

Request Body

user

string

The user identifier - email or userName based on the identityField property in <a href="#!/Identity_Providers/set_cloud_directory_idp" target="_blank"> cloud directory configuration.</a>

Path Parameters

tenantId

Required *

string

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

language

string

Preferred language for resource. Format as described at RFC5646.

Response

200 - The Cloud Directory user data is returned as a JSON object. Full user data can be found here.

400 - The tenant ID or request body is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

409 - The user account was not verified.

Forgot password confirmation result

POST /management/v4/{tenantId}/cloud_directory/forgot_password/confirmation_result

Get the forgot password flow confirmation result. Learn more.

Request

Request Body

Path Parameters

tenantId

Required *

string

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

Response

200 - The forgot password confirmation result is returned as a JSON object.

success

boolean

The status of the request.

uuid

string

The user's unique ID.

400 - The tenant ID or context is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

404 - The context was not found.

errorCode

string

message

string

Change password

POST /management/v4/{tenantId}/cloud_directory/change_password

Change the Cloud Directory user password. Learn more.

Request

Request Body

newPassword

Required *

string

The new password.

uuid

Required *

string

The Cloud Directory unique user Id.

changedIpAddress

string

The IP address and the changed password.

Path Parameters

tenantId

Required *

string

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

language

string

Preferred language for resource. Format as described at RFC5646.

Response

200 - The Cloud Directory user data is returned as a JSON object. Full user data can be found here.

400 - The tenant ID, uuid, or newPassword is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

Resend user notifications

POST /management/v4/{tenantId}/cloud_directory/resend/{templateName}

Resend user email notifications (for example, resend user verification email). Learn more.

Request

Request Body

uuid

Required *

string

The Cloud Directory unique user Id.

Path Parameters

tenantId

Required *

string

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.

templateName

Required *

string

The type of email template. The type can be "USER_VERIFICATION", "WELCOME", "PASSWORD_CHANGED" or "RESET_PASSWORD".

Query Parameters

language

string

Preferred language for resource. Format as described at RFC5646.

Response

202 - The notification is sent.

message

string

The message of the notification sent to the user.

400 - The tenant ID or request body is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

409 - The user account is not verified in cases when the template name is RESET_PASSOWRD.

410 - The user account is already confirmed in cases when the template name is CONFIRMATION.

Delete Cloud Directory User and Profile

DELETE /management/v4/{tenantId}/cloud_directory/remove/{userId}

Delete an existing Cloud Directory user and the associated profile. Learn more. Note: This action cannot be undone.

Request

Path Parameters

tenantId

Required *

string

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.

userId

Required *

string

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.

Query Parameters

Response

204 - The user and profile were deleted.

400 - Invalid tenant ID or user ID.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

Get languages

GET /management/v4/{tenantId}/config/ui/languages

Get the list of languages that can be used to customize email templates for Cloud Directory.

Request

Path Parameters

tenantId

Required *

string

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

Response

200 - The localization data is returned as a JSON object.

languages

array

The list of languages that can be used to customize email templates for CLoud Directory.

400 - The tenant ID or languages are missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

Update languages

PUT /management/v4/{tenantId}/config/ui/languages

Update the list of languages that can be used to customize email templates for Cloud Directory.

Request

Request Body

getLanguages

User localization configuration. Available languages codes

languages

Required *

array

The list of languages that can be used to customize email templates for CLoud Directory.

Path Parameters

tenantId

Required *

string

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

Response

204 - 'No content. The localization configuration was updated.'

400 - The tenant ID or request body is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

Get recent activity

GET /management/v4/{tenantId}/recent_authentications

This endpoint is deprecated, use recent_authentications_hidden instead.

Request

Path Parameters

tenantId

Required *

string

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

Response

200 - An array of recent activity is returned as a JSON object.

400 - The tenant ID parameter is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

Get recent activity

GET /management/v4/{tenantId}/recent_authentications_hidden

Get the recent activity for the App ID instance. Learn more.

Request

Path Parameters

tenantId

Required *

string

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

Response

200 - An array of recent activity is returned as a JSON object.

results

array

The details of the recent activity for the App instance.

400 - The tenant ID parameter is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

Get sender details

GET /management/v4/{tenantId}/config/cloud_directory/sender_details

Get the sender details configuration that is used by Cloud Directory when you are sending emails to your users. Learn more.

Request

Path Parameters

tenantId

Required *

string

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

Response

200 - The sender details configuration for a Cloud Directory email is returned as a JSON object.

senderDetails

object

The sender details of emails sent to your Cloud Directory users from App ID.

400 - The tenant ID parameter is missing or the request is invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

Update the sender details

PUT /management/v4/{tenantId}/config/cloud_directory/sender_details

Update the sender details configuration that is used by Cloud Directory when you are sending emails to your users. Learn more.

Request

Request Body

cloudDirectorySenderDetails

A JSON object that contains the sender details.

senderDetails

Required *

object

The sender details of emails sent to your Cloud Directory users from App ID.

from

Required *

object

The sender details of the emails.

reply_to

object

The details that users can use to reply to the emails.

linkExpirationSec

number

The expiration data of the link.

Path Parameters

tenantId

Required *

string

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

Response

204 - No content. The identity provider configuration was updated.

400 - The tenant ID or request body is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

Get action url

GET /management/v4/{tenantId}/config/cloud_directory/action_url/{action}

Get the custom url to redirect to when action is run. Learn more.

Request

Path Parameters

tenantId

Required *

string

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.

action

Required *

string

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.

Query Parameters

Response

200 - The action URL is returned as a JSON object.

actionUrl

string

The action URL.

400 - The tenant ID or action parameters are invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

Update action url

PUT /management/v4/{tenantId}/config/cloud_directory/action_url/{action}

Update the custom url to redirect to when action is run. Learn more.

Request

Request Body

actionUrl

Required *

string

The action URL.

Path Parameters

tenantId

Required *

string

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.

action

Required *

string

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.

Query Parameters

Response

200 - The action url is returned as a JSON object.

actionUrl

string

The action URL.

400 - The tenant ID or action parameters are invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

Delete action url

DELETE /management/v4/{tenantId}/config/cloud_directory/action_url/{action}

Delete the custom url to redirect to when action is run. Learn more.

Request

Path Parameters

tenantId

Required *

string

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.

action

Required *

string

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.

Query Parameters

Response

204 - No content. The action url was deleted.

400 - The tenant ID or action parameters are invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact a service owner or admin to verify permissions.

404 - The template does not exist.

Get password regex

GET /management/v4/{tenantId}/config/cloud_directory/password_regex

Get the regular expression used by App ID for password strength validation. Learn more.

Request

Path Parameters

tenantId

Required *

string

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

Response

200 - The defined regex expression escaped rule for acceptable password, base64 encoded regex expression and custom error message are returned as a JSON object.

regex

string

The regular expression that is used by App ID for password strength validation.

base64_encoded_regex

string

The regular expression that is used by App ID for password strength validation encoded in Base64.

error_message

string

The error message.

400 - The tenant ID is invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

Update password regex

PUT /management/v4/{tenantId}/config/cloud_directory/password_regex

Update the regular expression used by App ID for password strength validation. For example, the regular expression: `[1]*$` must be passed as: ``` { &nbsp;&nbsp;"base64_encoded_regex": "XltBLVphLXpcZF0qJA==", &nbsp;&nbsp;"error_message": "Must only contain letters and digits"} Learn more. ```

Request

Request Body

passwordRegexConfigParams

The Cloud Directory password regex configuration as a JSON object. If the configuration is not set, IBM App ID basic password regex is used.

regex

string

The regular expression that is used by App ID for password strength validation.

base64_encoded_regex

string

The regular expression that is used by App ID for password strength validation encoded in Base64.

error_message

string

The error message.

Path Parameters

tenantId

Required *

string

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

Response

200 - The password regex was updated.

regex

string

The regular expression that is used by App ID for password strength validation.

base64_encoded_regex

string

The regular expression that is used by App ID for password strength validation encoded in Base64.

error_message

string

The error message.

400 - The tenant ID or password regex parameters are invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

Get email dispatcher configuration

GET /management/v4/{tenantId}/config/cloud_directory/email_dispatcher

Get the configuration of email dispatcher that is used by Cloud Directory when you are sending emails to your users.

Request

Path Parameters

tenantId

Required *

string

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

Response

200 - The email dispatcher configuration is returned as a JSON object.

provider

string

The email provider.

sendgrid

object

The Sendgrid details.

custom

object

The custom details.

400 - The tenant ID is invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

Learn more.">

Update email dispatcher configuration

PUT /management/v4/{tenantId}/config/cloud_directory/email_dispatcher

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.

Request

Request Body

emailDispatcherParams

The Cloud Directory email dispatcher configuration, which is specified as a JSON object.

provider

Required *

string

The email provider.

sendgrid

object

The Sendgrid details.

apiKey

Required *

string

The Sendgrid API key.

custom

object

The custom details.

url

Required *

string

The URL.

authorization

Required *

object

The authorization data.

Path Parameters

tenantId

Required *

string

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

Response

200 - The email dispatcher was updated.

provider

string

The email provider.

sendgrid

object

The Sendgrid details.

custom

object

The custom details.

400 - The tenant ID or custom email dispatcher config are invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

Test the email provider configuration

POST /management/v4/{tenantId}/config/cloud_directory/email_settings/test

Send a message to a specific email to test your settings.

Request

Request Body

emailSettingsTestParams

The email dispatcher settings, which are specified as a JSON object.

emailTo

Required *

string

The email address to which the email will be sent.

emailSettings

Required *

object

The email settings.

provider

Required *

string

The email provider.

sendgrid

object

The Sendgrid details.

custom

object

The custom details.

senderDetails

Required *

object

The details of the sender.

from

Required *

object

The details of the sender.

reply_to

object

The details that users can use to reply to the emails.

Path Parameters

tenantId

Required *

string

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

Response

200 - The response status code and additional information from the email provider because of a failure are returned as a JSON object.

success

boolean

The status of the request.

dispatcherStatusCode

number

The status code of the dispatch request.

dispatcherResponse

object

The response of the dispatcher.

400 - The tenant ID or request body is invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

Test the email dispatcher configuration

POST /management/v4/{tenantId}/config/cloud_directory/email_dispatcher/test

Send a message to a specific email to test your configuration.

Request

Request Body

email

Required *

string

The email address to which you want to send your test message.

Path Parameters

tenantId

Required *

string

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

Response

200 - The response status code and headers from the custom email dispatcher are returned as a JSON object.

statusCode

number

The status code of the request.

headers

object

The headers of the email.

400 - The tenant ID or email value is invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

Test the MFA SMS dispatcher configuration

POST /management/v4/{tenantId}/config/cloud_directory/sms_dispatcher/test

Send a message to a specific phone number to test your MFA SMS configuration.

Request

Request Body

smsDispatcherTest

The phone number to which you want to send your test SMS message.

phone_number

Required *

string

The phone number to which you can send a message to test your MFA SMS configuration.

Path Parameters

tenantId

Required *

string

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

Response

200 - The response status code and headers from the SMS dispatcher are returned as a JSON object.

confirmationCode

number

The confirmation code.

phoneNumber

string

The phone number.

400 - The tenant ID or SMS channel configuration is invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

Get APM configuration

GET /management/v4/{tenantId}/config/cloud_directory/advanced_password_management

Get the configuration of advanced password management.

Request

Path Parameters

tenantId

Required *

string

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

Response

200 - View the advanced password management configuration.

advancedPasswordManagement

object

The configuration details of advanced password management.

400 - The tenant ID is invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

Update APM configuration

PUT /management/v4/{tenantId}/config/cloud_directory/advanced_password_management

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.

Request

Request Body

apmSchema

The Cloud Directory APM configuration, which is specified as a JSON object.

advancedPasswordManagement

Required *

object

The configuration details of advanced password management.

enabled

Required *

boolean

The status of the configuration.

passwordReuse

Required *

object

The configuration of password reuse.

preventPasswordWithUsername

Required *

object

The configuration of the prevention of password reuse.

passwordExpiration

Required *

object

The configuration of password expiration.

lockOutPolicy

Required *

object

The configuration of the lockout policy.

minPasswordChangeInterval

object

The configuration of the minimum interval for password change.

Path Parameters

tenantId

Required *

string

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

Response

200 - The advanced password management configuration is updated.

advancedPasswordManagement

object

The configuration details of advanced password management.

400 - The tenant ID or advanced password management configuration is invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

Search users

GET /management/v4/{tenantId}/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.

Request

Path Parameters

tenantId

Required *

string

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

email

string

Email (as retrieved from the Identity Provider).

id

string

The IdP specific user identifier.

dataScope

Required *

string

The user data.

startIndex

integer

The first result in a set list of results.

count

integer

The maximum number of results per page.

Response

200 - An array of results is returned as a JSON object.

totalResults

number

The number of search results.

itemsPerPage

number

The number of items per page.

requestOptions

object

The details of the request options.

users

array

The user details.

400 - The tenant ID is missing or invalid, or the request is missing the email or ID.

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

403 - You are not authorized to complete this operation. Contact the service owner or admin to verify your permissions.

500 - Returned because of an internal server error.

Pre-register a user profile

POST /management/v4/{tenantId}/users

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.

Request

Request Body

The user configuration and attributes.

idp

Required *

object

The identity provider.

idp-identity

Required *

string

The identity details of the user.

profile

object

The profile.

attributes

object

The custom attributes.

Path Parameters

tenantId

Required *

string

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

Response

201 - View the ID of the created user.

400 - The tenant ID, IdP type, or IdP identity ID is missing or invalid.

401 - The request is unauthorized by the platform. To be authorized, an IAM token with the valid permissions must be provided in Authorization header.

403 - You are not authorized to complete this operation. Contact the service owner or admin to verify your permissions.

409 - The user ID for the provided IdP exists.

500 - Returned because of an internal server error.

Export user profiles

GET /management/v4/{tenantId}/users/export

Export App ID user profiles, not including Cloud Directory and anonymous users. Learn more.

Request

Path Parameters

tenantId

Required *

string

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

startIndex

integer

The first result in a set list of results.

count

integer

The maximum number of results per page.

Response

200 - View a list of the App ID user profiles. You can see up to 50 users per request.

users

array

The list of App ID user profiles, not including Cloud Directory and anonymous users.

400 - The tenant ID is missing or invalid.

401 - The request is unauthorized by the platform. To be authorized, an IAM token with the valid permissions must be provided in the authorization header.

403 - You are not authorized to complete this operation. Contact the service owner or admin to verify your permissions.

404 - The tenant ID is not found.

Import user profiles

POST /management/v4/{tenantId}/users/import

Import App ID user profiles, not including Cloud Directory and anonymous users. Learn more.

Request

Request Body

exportUserProfile

The exported users as a JSON object (as returned by the export endpoint).

users

Required *

array

The list of App ID user profiles, not including Cloud Directory and anonymous users.

Path Parameters

tenantId

Required *

string

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

Response

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

added

number

The number of added user profiles.

failed

number

THe number of user profiles that failed to import.

failReasons

array

The reasons why user profiles failed to import.

400 - The tenant ID or request body is missing or invalid.

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

403 - You are not authorized to complete this operation. Contact the service owner or admin to verify your permissions.

404 - The tenant ID is not found.

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

Export all Cloud Directory users

POST /management/v4/{tenantId}/cloud_directory/export/all

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.

Request

Request Body

exportAllUsersInput

The encryption secret, email address, and expiration information as a JSON object.

emailAddress

Required *

string

The email address to which the notification is sent.

encryptionSecret

Required *

string

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 <a href="/swagger-ui/#/Management API - Cloud Directory Users/mgmt.cloudDirectoryImportAll" target="_blank">import all users</a> API. Note: IBM does not store the secret so if the secret is lost, you can't access the exported data.

expires

number

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.

Path Parameters

tenantId

Required *

string

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

Response

200 - An export job ID that can be used in the <a href="/swagger-ui/#/Management API - Cloud Directory Users/mgmt.cloudDirectoryExportStatus" target="_blank">export-status</a> API to query the status of your request is returned.

id

string

The export job ID that is returned from the <a href="/swagger-ui/#/Management API - Cloud Directory Users/mgmt.cloudDirectoryExportAll" target="_blank">export all users</a> API endpoint.

400 - The tenant ID, encryption secret, or email address is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

Get the export status of all Cloud Directory users

GET /management/v4/{tenantId}/cloud_directory/export/status

Get the status of the request that was made to export all of your Cloud Directory users from an instance of App ID.

Request

Path Parameters

tenantId

Required *

string

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

id

Required *

string

The export job ID that is returned from the <a href="/swagger-ui/#/Management API - Cloud Directory Users/mgmt.cloudDirectoryExportAll" target="_blank">export all users</a> API.

Response

200 - The details about the job status, when it was requested, started, completed, and expired are returned as a JSON object.

id

string

The export job ID that is returned from the <a href="/swagger-ui/#/Management API - Cloud Directory Users/mgmt.cloudDirectoryExportAll" target="_blank">export all users</a> API endpoint.

status

string

The status of your export request.

requested

string

When the job was requested in UTC (ISO 8601).

started

string

When the job started to be processed in UTC (ISO 8601).

completed

string

When the job completed in UTC (ISO 8601).

expires

string

When the download is no longer available.

400 - The tenant ID or export job ID is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

delete endpoint.">

Download exported file of all Cloud Directory users

GET /management/v4/{tenantId}/cloud_directory/export/download

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.

Request

Path Parameters

tenantId

Required *

string

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

id

Required *

string

The export job ID that is returned from the <a href="/swagger-ui/#/Management API - Cloud Directory Users/mgmt.cloudDirectoryExportAll" target="_blank">export all users</a> API.

Response

200 - The full list of users in your Cloud Directory and their profiles is returned as a JSON attachment.

users

array

The full list of users in your Cloud Directory and their profiles as a JSON object.

204 - The file that contains the list of users in your Cloud Directory and their profiles was not found.

400 - The tenant ID or export job ID is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

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 exported file of all Cloud Directory users

DELETE /management/v4/{tenantId}/cloud_directory/export/download

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

Request

Path Parameters

tenantId

Required *

string

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

id

Required *

string

The export job ID that is returned from the <a href="/swagger-ui/#/Management API - Cloud Directory Users/mgmt.cloudDirectoryExportAll" target="_blank">export all users</a> API.

Response

200 - All content that is associated with the export job ID was successfully deleted.

400 - The tenant ID or export job ID is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

404 - No content found to delete.

Import all Cloud Directory users

POST /management/v4/{tenantId}/cloud_directory/import/all

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.

Request

Request Body

Path Parameters

tenantId

Required *

string

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

encryption_secret

Required *

string

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 <a href="/swagger-ui/#/Management API - Cloud Directory Users/mgmt.cloudDirectoryImportAll" target="_blank">import all users</a> API. Note: IBM does not store the secret so if the secret is lost, you can't access the exported data.

emailAddress

Required *

string

The email address to which the notification is sent.

Response

200 - 'An import ID that can be used to get the import status of your request is returned.'

id

string

The export job ID that is returned from the <a href="/swagger-ui/#/Management API - Cloud Directory Users/mgmt.cloudDirectoryExportAll" target="_blank">export all users</a> API endpoint.

400 - The tenant ID, encryption secret, email address, or request body is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

Get the import status of all Cloud Directory users

GET /management/v4/{tenantId}/cloud_directory/import/status

Get the status of the request to import all Cloud Directory users that are associated with the specific import job ID and tenant ID.

Request

Path Parameters

tenantId

Required *

string

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

id

Required *

string

The import job ID that is returned from the <a href="/swagger-ui/#/Management API - Cloud Directory Users/mgmt.cloudDirectoryImportAll" target="_blank">import all users</a> API.

Response

200 - Details about the job status, when it was requested, started, and completed are returned as a JSON object.

id

string

The import job ID.

status

string

The status of your import request.

requested

string

When the job was requested in UTC (ISO 8601)

started

string

When the job started to be processed in UTC (ISO 8601)

completed

string

When the job completed in UTC (ISO 8601)

expires

string

When the download will no longer be available

result

object

The result of the import

400 - The tenant ID or import job ID is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

View all roles

GET /management/v4/{tenantId}/roles

Obtain a list of the roles that are associated with your registered application.

Request

Path Parameters

tenantId

Required *

string

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

Response

200 - The roles for the registered application are returned as a JSON object.

roles

array

A list of the roles that are associated with your registered application.

400 - The tenant ID or user ID is missing or invalid.

401 - The request is unauthorized. Be sure that you pass a valid IAM token in the authorization header of your request.

403 - You have insufficient permissions. Contact your administrator to verify your permissions.

Create a role

POST /management/v4/{tenantId}/roles

Create a role for a registered application.

Request

Request Body

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.

name

Required *

string

The role name.

description

string

The role description.

access

Required *

array

The access data.

Path Parameters

tenantId

Required *

string

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

Response

201 - The role for the registered application is created and returned as a JSON object.

id

string

The role ID.

name

string

The role name.

description

string

The description.

access

array

The access data.

400 - The payload is missing or invalid.

401 - The request is unauthorized. Be sure that you pass a valid IAM token in the authorization header of your request.

403 - You have insufficient permissions. Contact your administrator to verify your permissions.

409 - The role exists. Choose a new name or update your existing role.

View a specific role

GET /management/v4/{tenantId}/roles/{roleId}

By using the role ID, obtain the information for a specific role that is associated with a registered application.

Request

Path Parameters

tenantId

Required *

string

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.

roleId

Required *

string

The role identifier. You can find the roleId by navigating to App ID > Profiles and roles > Roles in the UI.

Query Parameters

Response

200 - The data that is associated with the role is returned as a JSON object.

id

string

The role ID.

name

string

The role name.

description

string

The role description.

access

array

The access data.

400 - The tenant ID or user ID is missing or invalid.

401 - The request is unauthorized. Be sure that you pass a valid IAM token in the authorization header of your request.

403 - You have insufficient permissions. Contact your administrator to verify your permissions.

404 - The role was not found. Verify your role ID by listing all of the roles that are associated with your application.

Update a role

PUT /management/v4/{tenantId}/roles/{roleId}

Update an existing role. Learn more.

Request

Request Body

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.

name

Required *

string

The role name.

description

string

The role description.

access

Required *

array

The access data.

Path Parameters

tenantId

Required *

string

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.

roleId

Required *

string

The role identifier. You can find the roleId by navigating to App ID > Profiles and roles > Roles in the UI.

Query Parameters

Response

200 - The role is updated and the data that is associated with the role is returned as a JSON object.

id

string

name

string

The name.

description

string

The description.

access

array

The access data.

400 - The payload is missing or invalid.

401 - The request is unauthorized. Be sure that you pass a valid IAM token in the authorization header of your request.

403 - You have insufficient permissions. Contact your administrator to verify your permissions.

404 - The role was not found. Verify your role ID by listing all of the roles that are associated with your application.

Delete a role

DELETE /management/v4/{tenantId}/roles/{roleId}

Delete an existing role.

Request

Path Parameters

tenantId

Required *

string

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.

roleId

Required *

string

The role identifier. You can find the roleId by navigating to App ID > Profiles and roles > Roles in the UI.

Query Parameters

Response

202 - The Delete request is accepted.

401 - The request is unauthorized. Be sure that you pass a valid IAM token in the authorization header of your request.

403 - You have insufficient permissions. Contact your administrator to verify your permissions.

Delete user

DELETE /management/v4/{tenantId}/users/{id}

Delete a user by ID. Learn more.

Request

Path Parameters

tenantId

Required *

string

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.

id

Required *

string

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.

Query Parameters

Response

204 - The user was deleted successfully.

400 - The tenant ID or user ID is missing or invalid.

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

403 - You are not authorized to complete this operation. Contact the service owner or admin to verify your permissions.

404 - The user is not found.

500 - Returned because of an internal server error.

Revoke refresh token

POST /management/v4/{tenantId}/users/{id}/revoke_refresh_token

Revoke all the refresh tokens that are issued for the specific user. Learn more.

Request

Path Parameters

tenantId

Required *

string

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.

id

Required *

string

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.

Query Parameters

Response

204 - No content. The users refresh token was revoked.

400 - The tenant ID or user ID is missing or invalid.

401 - The request is unauthorized by the platform. To be authorized, an IAM token with the valid permissions must be provided in the authorization header.

403 - You are not authorized to complete this operation. Contact the service owner or admin to verify your permissions.

404 - The user is not found.

500 - Returned because of an internal server error.

Get user profile

GET /management/v4/{tenantId}/users/{id}/profile

Get the profile of a specific user. Learn more.

Request

Path Parameters

tenantId

Required *

string

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.

id

Required *

string

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.

Query Parameters

Response

200 - The user profile is returned as a JSON object.

400 - The tenant ID or ID is missing or invalid.

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

403 - You are not authorized to complete this operation. Contact the service owner or admin to verify your permissions.

404 - The user is not found.

500 - Returned because of an internal server error.

Update user profile

PUT /management/v4/{tenantId}/users/{id}/profile

Update a user profile. Learn more.

Request

Request Body

The user's profile as a JSON object. Only the 'attributes' field is accepted.

attributes

Required *

object

The profile attributes.

Path Parameters

tenantId

Required *

string

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.

id

Required *

string

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.

Query Parameters

Response

200 - The updated user profile is returned as a JSON object.

400 - The tenant ID, user ID, or request body is missing or invalid.

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

403 - You are not authorized to complete this operation. Contact the service owner or admin to verify your permissions.

404 - The user is not found.

500 - Returned because of an internal server error.

Get a user's roles

GET /management/v4/{tenantId}/users/{id}/roles

View a list of roles that are associated with a specific user.

Request

Path Parameters

tenantId

Required *

string

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.

id

Required *

string

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.

Query Parameters

Response

200 - The list of roles is returned as a JSON object.

roles

array

The user's roles.

400 - The tenant ID or user ID is missing or invalid.

401 - The request is unauthorized. Be sure that you pass a valid IAM token in the authorization header of your request.

403 - You have insufficient permissions. Contact your administrator to verify your permissions.

404 - The user wasn't found.

Update a user's roles

PUT /management/v4/{tenantId}/users/{id}/roles

Update which roles are associated with a specific user or assign a role to a user for the first time. Learn more.

Request

Request Body

Path Parameters

tenantId

Required *

string

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.

id

Required *

string

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.

Query Parameters

Response

200 - The role is successfully associated with the user.

roles

array

The user's roles.

400 - The tenant ID or user ID is missing or invalid.

401 - The request is unauthorized. Be sure that you pass a valid IAM token in the authorization header of your request.

403 - You have insufficient permissions. Contact your administrator to verify your permissions.

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

Get applications

GET /management/v4/{tenantId}/applications

View all applications registered with the App ID Instance.

Request

Path Parameters

tenantId

Required *

string

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

Response

200 - A list of all the applications that are registered with the App ID tenant ID is returned as a JSON object.

applications

array

The applications registered with the App ID instance.

400 - The tenant ID is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

Create application

POST /management/v4/{tenantId}/applications

Register a new application with the App ID instance.

Request

Request Body

registerServerApp

The application registration payload. Application name cannot exceed 50 characters.

name

Required *

string

The application name to be registered. Application name cannot exceed 50 characters.

type

string

The type of application to be registered. Allowed types are regularwebapp and singlepageapp.

Path Parameters

tenantId

Required *

string

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

Response

200 - The new registered application data is returned as a JSON object.

applications

array

The applications registered with the App ID instance.

400 - The tenant ID or request body is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

500 - Returned because of an internal server error.

Get application

GET /management/v4/{tenantId}/applications/{clientId}

Get a specific application registered with the App ID Instance.

Request

Path Parameters

tenantId

Required *

string

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.

clientId

Required *

string

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.

Query Parameters

Response

200 - A specific application that is registered with the App ID tenant ID is returned as a JSON object.

applications

array

The applications registered with the App ID instance.

400 - The tenant ID is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

Update application

PUT /management/v4/{tenantId}/applications/{clientId}

Update an application registered with the App ID instance.

Request

Request Body

updateApp

The application registration payload. Application name cannot exceed 50 characters.

name

Required *

string

The application name to be updated. Application name cannot exceed 50 characters.

Path Parameters

tenantId

Required *

string

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.

clientId

Required *

string

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.

Query Parameters

Response

201 - The updated application data is returned as a JSON object.

applications

array

The applications registered with the App ID instance.

400 - The tenant ID or request body is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

404 - The application was not be found.

500 - Returned because of an internal server error.

Delete application

DELETE /management/v4/{tenantId}/applications/{clientId}

Delete an application registered with the App ID instance. Note: This action cannot be undone.

Request

Path Parameters

tenantId

Required *

string

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.

clientId

Required *

string

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.

Query Parameters

Response

204 - The application was deleted.

400 - The tenant ID is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

404 - The application was not found.

Get application scopes

GET /management/v4/{tenantId}/applications/{clientId}/scopes

View the defined scopes for an application that is registered with an App ID instance.

Request

Path Parameters

tenantId

Required *

string

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.

clientId

Required *

string

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.

Query Parameters

Response

200 - The scopes for the registered application are returned as a JSON object.

scopes

array

The scopes.

400 - The tenant ID or client ID is missing or invalid.

401 - The request is unauthorized. Be sure that you pass a valid IAM token in the authorization header of your request.

403 - You have insufficient permissions. Contact your administrator to verify your permissions.

Add application scope

PUT /management/v4/{tenantId}/applications/{clientId}/scopes

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.

Request

Request Body

scopes

Required *

array

The scopes.

Path Parameters

tenantId

Required *

string

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.

clientId

Required *

string

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.

Query Parameters

Response

200 - The updated scopes for the registered application are returned as a JSON object.

scopes

array

The scopes.

400 - The tenant ID, client ID, or request body is missing or invalid.

401 - The request is unauthorized. Be sure that you pass a valid IAM token in the authorization header of your request.

403 - You have insufficient permissions. Contact your administrator to verify your permissions.

404 - The application cannot be found.

Get application roles

GET /management/v4/{tenantId}/applications/{clientId}/roles

View the defined roles for an application that is registered with an App ID instance.

Request

Path Parameters

tenantId

Required *

string

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.

clientId

Required *

string

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.

Query Parameters

Response

200 - The roles for the registered application are returned as a JSON object.

roles

array

The user's roles.

400 - The tenant ID or client ID is missing or invalid.

401 - The request is unauthorized. Be sure that you pass a valid IAM token in the authorization header of your request.

403 - You have insufficient permissions. Contact your administrator to verify your permissions.

Add application role

PUT /management/v4/{tenantId}/applications/{clientId}/roles

Update the roles for a registered application.

Request

Request Body

Path Parameters

tenantId

Required *

string

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.

clientId

Required *

string

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.

Query Parameters

Response

200 - The role is successfully associated with the application.

roles

array

The user's roles.

400 - The tenant ID, client ID, or request body is missing or invalid.

401 - The request is unauthorized. Be sure that you pass a valid IAM token in the authorization header of your request.

403 - You have insufficient permissions. Contact your administrator to verify your permissions.

404 - The application cannot be found.

Get tenant audit status

GET /management/v4/{tenantId}/config/capture_runtime_activity

Get a JSON object that contains the auditing status of the tenant.

Request

Path Parameters

tenantId

Required *

string

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

Response

200 - The auditing status of the tenant is returned as a JSON object.

400 - The tenant ID is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

Update tenant audit status

PUT /management/v4/{tenantId}/config/capture_runtime_activity

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.

Request

Request Body

The new audit status, which is specified as a JSON object.

isActive

Required *

boolean

The status of the configuration.

Path Parameters

tenantId

Required *

string

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

Response

204 - The tenant was updated.

400 - The tenant ID or request body is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

Get channels

GET /management/v4/{tenantId}/config/cloud_directory/mfa/channels

Get all the MFA channels registered with the App ID Instance.

Request

Path Parameters

tenantId

Required *

string

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

Response

200 - A list of all the MFA channels that are registered with the App ID tenant ID is returned as a JSON object.

channels

array

A list of all the MFA channels that are registered with a specific App ID instance.

400 - The tenant ID is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

Get channel

GET /management/v4/{tenantId}/config/cloud_directory/mfa/channels/{channel}

Get a specific MFA channel registered with the App ID Instance.

Request

Path Parameters

tenantId

Required *

string

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.

channel

Required *

string

The MFA channel.

Query Parameters

Response

200 - A specific channel that is registered with the App ID tenant ID is returned as a JSON object.

isActive

boolean

The status of the configuration.

type

string

The type of channel.

config

object

The configuration of the channel.

400 - The tenant ID is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

Update channel

PUT /management/v4/{tenantId}/config/cloud_directory/mfa/channels/{channel}

Enable or disable a registered MFA channel on the App ID instance. Learn more.

Request

Request Body

updateMfaChannel

The MFA channel payload.

isActive

Required *

boolean

The status of the configuration.

config

object

The details of the configuration.

Path Parameters

tenantId

Required *

string

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.

channel

Required *

string

The MFA channel.

Query Parameters

Response

200 - The updated channel data is returned as a JSON object.

isActive

boolean

The status of the configuration.

type

string

The type of channel.

config

object

The configuration of the channel.

400 - The tenant ID or request body is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

404 - The channel was not be found.

500 - Returned because of an internal server error.

Get an extension configuration

GET /management/v4/{tenantId}/config/cloud_directory/mfa/extensions/{name}

View a registered extension's configuration for an instance of App ID. Learn more.

Request

Path Parameters

tenantId

Required *

string

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.

name

Required *

string

The name of the extension.

Query Parameters

Response

200 - The extension configuration is returned as a JSON object.

isActive

boolean

The status of the configuration.

config

object

The congiguration details of a registered extension.

400 - The tenant ID or request body is either missing or invalid.

401 - The request is unauthorized. Be sure that you pass a valid IAM token in the authorization header of your request.

403 - You have insufficient permissions. Contact your administrator or service owner to verify your permissions.

500 - Internal server error. Try again in a few minutes.

Update an extension configuration

PUT /management/v4/{tenantId}/config/cloud_directory/mfa/extensions/{name}

Set or update a registered extension's configuration for an instance of App ID. Learn more.

Request

Request Body

updateExtensionConfig

The extension configuration payload.

isActive

Required *

boolean

The status of the configuration.

config

object

The congiguration details of a registered extension.

url

string

The extension's URL.

headers

object

The headers.

Path Parameters

tenantId

Required *

string

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.

name

Required *

string

The name of the extension.

Query Parameters

Response

200 - A JSON object that contains either true or false is returned, depending on your configuration.

isActive

boolean

The status of the configuration.

config

object

The congiguration details of a registered extension.

400 - The tenant ID or request body is either missing or invalid.

401 - The request is unauthorized. Be sure that you pass a valid IAM token in the authorization header of your request.

403 - You have insufficient permissions. Contact your administrator or service owner to verify your permissions.

500 - Internal server error. Try again in a few minutes.

Enable or disable an extension

PUT /management/v4/{tenantId}/config/cloud_directory/mfa/extensions/{name}/active

Update the status of a registered extension for an instance of App ID to enabled or disabled. Learn more.

Request

Request Body

extensionActive

The extension enabled.

isActive

Required *

boolean

The status of the configuration.

config

object

The configuration details of the registered extension.

Path Parameters

tenantId

Required *

string

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.

name

Required *

string

The name of the extension.

Query Parameters

Response

200 - A JSON object that contains either true or false is returned, depending on your configuration.

isActive

boolean

The status of the configuration.

config

object

The configuration details of the registered extension.

400 - The tenant ID or request body is either missing or invalid.

401 - The request is unauthorized. Be sure that you pass a valid IAM token in the authorization header of your request.

403 - You have insufficient permissions. Contact your administrator or service owner to verify your permissions.

500 - Internal server error. Try again in a few minutes.

Test the extension configuration

POST /management/v4/{tenantId}/config/cloud_directory/mfa/extensions/{name}/test

Test an extension configuration. Learn more.

Request

Path Parameters

tenantId

Required *

string

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.

name

Required *

string

The name of the extension.

Query Parameters

Response

200 - The response status code, the response body, and headers from the extension's URL are returned.

statusCode

number

The status code of the test.

headers

object

The response headers.

400 - The tenant ID or extension name is missing or invalid.

401 - The request is unauthorized. Be sure that you pass a valid IAM token in the authorization header of your request.

403 - You have insufficient permissions. Contact your administrator or service owner to verify your permissions.

Get MFA configuration

GET /management/v4/{tenantId}/config/cloud_directory/mfa

Get the MFA configuration registered with the App ID Instance.

Request

Path Parameters

tenantId

Required *

string

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

Response

200 - The MFA configuration that is registered with the App ID tenant is returned as a JSON object.

isActive

boolean

The status of the configuration.

400 - The tenant ID is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

Update MFA configuration

PUT /management/v4/{tenantId}/config/cloud_directory/mfa

Update MFA configuration on the App ID instance.

Request

Request Body

updateMfaConfig

The MFA configuration payload.

isActive

Required *

boolean

The status of the configuration.

config

object

The configuration details of the MFA channel.

Path Parameters

tenantId

Required *

string

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

Response

200 - The updated MFA configuration data is returned as a JSON object.

isActive

boolean

The status of the configuration.

400 - The tenant ID or request body is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

500 - Returned because of an internal server error.

Get SSO configuration

GET /management/v4/{tenantId}/config/cloud_directory/sso

View the Single sign-on (SSO) configuration registered with the App ID Instance.

Request

Path Parameters

tenantId

Required *

string

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

Response

200 - The SSO configuration that is registered with the App ID tenant ID is returned as a JSON object.

400 - The tenant ID is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

Update SSO configuration

PUT /management/v4/{tenantId}/config/cloud_directory/sso

Update the Single sign-on (SSO) configuration on the App ID instance. Learn more.

Request

Request Body

updateSSOConfig

The SSO configuration payload.

isActive

Required *

boolean

The status of the configuration.

inactivityTimeoutSeconds

Required *

number

The time limit of activity after which users are logged out of their account.

logoutRedirectUris

Required *

array

The logout redirect URL.

Path Parameters

tenantId

Required *

string

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

Response

201 - The updated SSO configuration data is returned as a JSON object.

400 - The tenant ID or request body is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

500 - Returned because of an internal server error.

Get the rate limit configuration

GET /management/v4/{tenantId}/config/cloud_directory/rate_limit

Get the rate limit configuration registered with the App ID Instance.

Request

Path Parameters

tenantId

Required *

string

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

Response

200 - The rate limit configuration that is registered with the App ID tenant is returned as a JSON object.

400 - The tenant ID or request body is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

Update the rate limit configuration

PUT /management/v4/{tenantId}/config/cloud_directory/rate_limit

Update the rate limit configuration on the App ID instance. Learn more.

Request

Request Body

updateRateLimitConfig

The rate limit configuration payload.

signUpLimitPerMinute

Required *

integer

The sign-up limit per minute.

signInLimitPerMinute

Required *

integer

The sign-in limit per minute.

Path Parameters

tenantId

Required *

string

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

Response

201 - The updated rate limit configuration data is returned as a JSON object.

400 - The tenant ID or request body is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

Get Cloud Directory users

GET /management/v4/{tenantId}/cloud_directory/Users

Get the list of Cloud Directory users. Learn more.

Request

Path Parameters

tenantId

Required *

string

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

startIndex

integer

The first result in a set list of results.

count

integer

The maximum number of results per page.

query

string

The users by identity field.

Response

200 - The Cloud Directory users data is returned as a JSON object. Find more information about full user data here.

totalResults

number

The number of results.

itemsPerPage

number

The number of items per page.

active

boolean

The status of the user profile.

lockedUntil

integer

The time limit until which the user is locked out of their account.

Resources

array

The list of Cloud Directory users.

400 - The tenant ID is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

Create a Cloud Directory user

POST /management/v4/{tenantId}/cloud_directory/Users

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.

Request

Request Body

Path Parameters

tenantId

Required *

string

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

Response

201 - The new Cloud Directory user data is returned as a JSON object. Full user data can be found here.

400 - The tenant ID or request body is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

409 - The email exists in the directory. You can try searching for the user or registering a different email.

Get a Cloud Directory user

GET /management/v4/{tenantId}/cloud_directory/Users/{userId}

Get the requested Cloud Directory user object. Learn more.

Request

Path Parameters

tenantId

Required *

string

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.

userId

Required *

string

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.

Query Parameters

Response

200 - The updated Cloud Directory user data is returned as a JSON object. Full user data can be found here.

400 - The tenant ID or user ID is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

404 - The Cloud Directory user was not found.

Update a Cloud Directory user

PUT /management/v4/{tenantId}/cloud_directory/Users/{userId}

Update an existing Cloud Directory user. Learn more.

Request

Request Body

updateUser

The Cloud Directory user data.

emails

Required *

emails

The email details.

userName

string

The user's username.

password

string

The password.

active

boolean

The 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).

lockedUntil

integer

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

Path Parameters

tenantId

Required *

string

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.

userId

Required *

string

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.

Query Parameters

Response

200 - The updated Cloud Directory user data is returned as a JSON object. Full user data can be found here.

400 - The tenant ID or request body is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

404 - The Cloud Directory user was not found.

409 - The email exists in the directory. You can try searching for the user or registering a different email.

Delete a Cloud Directory user

DELETE /management/v4/{tenantId}/cloud_directory/Users/{userId}

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.

Request

Path Parameters

tenantId

Required *

string

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.

userId

Required *

string

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.

Query Parameters

Response

204 - The user was deleted from the Cloud Directory.

400 - The tenant ID is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

404 - The Cloud Directory user was not found.

Invalidate all SSO sessions

POST /management/v4/{tenantId}/cloud_directory/Users/{userId}/sso/logout

Invalidate all the user's SSO sessions. Learn more.

Request

Path Parameters

tenantId

Required *

string

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.

userId

Required *

string

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.

Query Parameters

Response

204 - No content. All SSO sessions of the user were invalidated.

400 - The tenant ID is invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

404 - The Cloud Directory user was not found.

export all users API endpoint. Learn more.">

Export Cloud Directory users

GET /management/v4/{tenantId}/cloud_directory/export

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.

Request

Path Parameters

tenantId

Required *

string

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

encryption_secret

Required *

string

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 <a href="/swagger-ui/#/Management API - Cloud Directory Users/mgmt.cloudDirectoryImportAll" target="_blank">import all users</a> API. Note: IBM does not store the secret so if the secret is lost, you can't access the exported data.

startIndex

integer

The first result in a set list of results.

count

integer

The maximum number of results per page. Limit to 50 users per request.

Response

200 - 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.'

users

array

The list of Cloud Directory users with their profile attributes and hashed passwords.

active

boolean

The status of the user profile.

lockedUntil

integer

The number of milliseconds of inactivity after which users will be locked out of their account.

400 - The tenant ID or user ID is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

404 - The Cloud Directory user was not found.

Import Cloud Directory users

POST /management/v4/{tenantId}/cloud_directory/import

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.

Request

Request Body

exportUser

The exported Cloud Directory users as a JSON object (as returned by the export endpoint).

users

Required *

array

The list of Cloud Directory users with their profile attributes and hashed passwords.

active

boolean

The status of the user profile.

lockedUntil

integer

The number of milliseconds of inactivity after which users will be locked out of their account.

Path Parameters

tenantId

Required *

string

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

encryption_secret

Required *

string

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 <a href="/swagger-ui/#/Management API - Cloud Directory Users/mgmt.cloudDirectoryImportAll" target="_blank">import all users</a> API. Note: IBM does not store the secret so if the secret is lost, you can't access the exported data.

Response

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

added

number

The number of profiles that are imported successfully.

active

boolean

The status of the request.

lockedUntil

integer

The number of milliseconds of inactivity after which users will be locked of their accounts.

failed

number

The number of users that failed to import.

failReasons

array

The reasons why users failed to import.

400 - The tenant ID or user ID is missing or invalid.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

404 - The Cloud Directory user was not found.

Get Cloud Directory SCIM and Attributes

GET /management/v4/{tenantId}/cloud_directory/{userId}/userinfo

Get the Cloud Directory user System for Cross-domain Identity Management (SCIM) and the profile related to it. Learn more.

Request

Path Parameters

tenantId

Required *

string

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.

userId

Required *

string

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.

Query Parameters

Response

200 - The user's data is returned as a JSON object.

sub

string

The request's ID.

identities

array

The details of the user's identity.

attributes

object

The user's profile attributes.

400 - Invalid tenant ID/user ID.

401 - The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.

403 - The user has insufficient permissions. Contact the service owner or admin to verify permissions.

404 - The user is not found.

Delete a TOTP registration

DELETE /management/v4/{tenantId}/cloud_directory/Users/{userId}/mfa/totp

Delete a user's time-based one-time passcode (TOTP) registration. If a user never used TOTP, this operation has no effect.

Request

Path Parameters

tenantId

Required *

string

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.

userId

Required *

string

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.

Query Parameters

Response

200 - The TOTP registration was deleted successfully.

400 - The tenant ID or user ID is missing or invalid.

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

403 - You are not authorized to complete this operation. Contact the service owner or admin to verify your permissions.

404 - The user was not found.

500 - Returned because of an internal server error.


  1. A-Za-z\d ↩︎