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: ``` { "base64_encoded_regex": "XltBLVphLXpcZF0qJA==", "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.
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
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
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.
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.
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.
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.
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 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.
A-Za-z\d ↩︎