Introduction

Application security can be incredibly complicated. For most developers, it's one of the hardest part of creating an app. How can you be sure that you are protecting your users information? By integrating IBM® Cloud App ID into your apps, you can secure resources and add authentication; even when you don't have a lot of security experience. By requiring users to sign in to your app, you can store user data such as app preferences or information from the public social profiles, and then use that data to customize each experience of your app. With this API you can manage your instances of the service.

Don't see the API endpoint that you're looking for? Check out the other APIs for Authorization and authentication and Profiles.

Authentication

This API is protected by IBM Cloud Identity and Access Management. For help obtaining a token, check out the Getting an IAM token with an API key. To define fine grain access policies, you must have an instance of App ID that was created after March 15, 2018.

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. Check out the following table for a general description of each error type.

HTTP error code Description Recovery
200 Success The request was successful.
400 Request error There is some type of error in the request. Be sure that it is formatted in proper JSON.
401 Invalid token The request does not contain a valid access token. Obtain a new access token.
404 Not found The requested resource couldn't be found.
408 Request timeout The connection to the server timed out. Wait a few minutes and try again.
500 Internal server error The service is currently unavailable. Please wait a few minutes and try again.

Methods

Get Facebook IDP configuration

Returns the Facebook identity provider configuration.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Response

Status Code

  • Returns a JSON object of the Facebook identity provider configuration, including the status and credentials.
    For more information, check out the docs.

  • The tenantId or request body is missing or invalid.

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

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

  • Returned in case of internal server error.

Example responses

Update Facebook IDP configuration

Configure Facebook to set up a single sign-on experience for your users. By using Facebook, users are able to sign in with credentials with which they are already familiar.
For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

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

Example:
Response

Status Code

  • The Facebook configuration was updated. Returns a JSON object of the idp data.

  • The tenantId or request body is missing or invalid.

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

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

  • Returned in case of internal server error.

No Sample Response

This method does not specify any sample responses.

Get Google IDP configuration

Returns the Google identity provider configuration.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Response

Status Code

  • Returns a JSON object of the Google identity provider configuration, including the status and credentials.
    For more information, check out the docs.

  • The tenantId or request body is missing or invalid.

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

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

  • Returned in case of internal server error.

No Sample Response

This method does not specify any sample responses.

Update Google IDP configuration

Configure Google to set up a single sign-on experience for your users. By using Google, users are able to sign in with credentials with which they are already familiar.
For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

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

Example:
Response

Status Code

  • The Google configuration was updated. Returns a JSON object of the idp data.

  • The tenantId or request body is missing or invalid. The tenantId can be found in the service credentials.

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

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

  • Returned in case of internal server error.

No Sample Response

This method does not specify any sample responses.

Returns the Custom identity configuration.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Response

Status Code

  • Returns a JSON object of the Custom identity configuration containing the PEM public key and the isActive status.

  • The tenantId or request body is missing or invalid.

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

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

  • Returned in case of internal server error.

No Sample Response

This method does not specify any sample responses.

Update or change the configuration of the Custom identity.

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

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

The identity provider configuration as a JSON object.

Response

Status Code

  • The Custom identity configuration was updated. Returns a JSON object of the updated configuration.

  • The tenantId or request body is missing or invalid.

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

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

  • Returned in case of internal server error.

No Sample Response

This method does not specify any sample responses.

Get Cloud Directory IDP configuration

Returns the cloud directory identity provider configuration. For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Response

Status Code

  • Returns a JSON object of the cloud directory identity provider configuration, including the status and credentials.

  • The tenantId or request body is missing or invalid.

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

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

  • Returned in case of internal server error.

No Sample Response

This method does not specify any sample responses.

Update Cloud Directory IDP configuration

Configure cloud directory to set up a single sign-on experience for your users. With cloud directory users can use their email and a password of their choice to log in to your applications.
For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

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

Response

Status Code

  • The cloud directory configuration was updated. Returns a JSON object of the idp data.

  • The tenantId or request body is missing or invalid.

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

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

  • Returned in case of internal server error.

No Sample Response

This method does not specify any sample responses.

Get SAML IDP configuration

Returns the SAML identity provider configuration, including status and credentials. For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Response

Status Code

  • Returns the identity provider configuration for SAML as a JSON object.

  • The tenantId or request body is missing or invalid. The tenantId can be found in the service credentials.

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

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

  • Returned in case of internal server error.

No Sample Response

This method does not specify any sample responses.

Update SAML IDP configuration

Configure SAML to set up a single sign-on experience for your users.
For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

The identity provider configuration as a JSON object.

Response

Status Code

  • The SAML configuration was updated. Returns a JSON object of the idp data.

  • The tenantId or request body is missing or invalid.

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

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

  • Returned in case of internal server error.

No Sample Response

This method does not specify any sample responses.

Get tokens configuration

Returns the token configuration. For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Response

Status Code

  • Returns a JSON object of the App ID tokens properties.

  • The tenantId or request body is missing or invalid.

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

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

No Sample Response

This method does not specify any sample responses.

Update tokens configuration

Update the tokens' configuration to fine-tune the expiration times of access, id and refresh tokens, to enable/disable refresh and anonymous tokens, and to configure custom claims. When a token config object is not included in the set, its value will be reset back to default.
For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

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

Response

Status Code

  • The token configuration was updated.

  • The tenantId or request body is missing or invalid.

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

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

No Sample Response

This method does not specify any sample responses.

Get redirect URIs

Returns the list of the redirect URIs that can be used as callbacks of App ID authentication flow. For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Response

Status Code

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

  • The tenantId parameter is missing or invalid.

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

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

No Sample Response

This method does not specify any sample responses.

Update redirect URIs

Update the list of the redirect URIs that can be used as callbacks of App ID authentication flow.
For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

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

Response

Status Code

  • No content. The redirect URIs were updated.

  • The tenantId or request body is missing or invalid.

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

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

No Sample Response

This method does not specify any sample responses.

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

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Response

Status Code

  • The current profiles status is returned as a JSON object.

  • The tenantId is missing or invalid.

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

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

No Sample Response

This method does not specify any sample responses.

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

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

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

Response

Status Code

  • No content. The user profiles status was updated.

  • The tenantId or request body is missing or invalid.

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

  • The has insufficient permissions. Contact the service owner or admin to verify permissions.

No Sample Response

This method does not specify any sample responses.

Get widget texts

Get the theme texts of the App ID login widget.
For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Response

Status Code

  • The current color configuration is returned as a JSON object.

  • The tenantId is missing or invalid.

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

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

No Sample Response

This method does not specify any sample responses.

Update widget texts

Update the texts of the App ID login widget.
For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

The texts of the widget.

Response

Status Code

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

  • The tenantId or request body is missing or invalid.

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

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

No Sample Response

This method does not specify any sample responses.

Get widget colors

Get the colors of the App ID login widget.
For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Response

Status Code

  • The current color configuration is returned as a JSON object.

  • The tenantId is missing or invalid.

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

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

No Sample Response

This method does not specify any sample responses.

Update widget colors

Update the colors of the App ID login widget.
For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

The colors of the widget.

Response

Status Code

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

  • The tenantId or request body is missing or invalid.

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

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

No Sample Response

This method does not specify any sample responses.

Returns the link to the custom logo image of the login widget For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Response

Status Code

  • A JSON object with the current media configurations.

  • The tenantId, file type, or file size are invalid or missing. The file must be either a JPG or PNG that is less than 100kb.

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

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

No Sample Response

This method does not specify any sample responses.

You can update the image file shown in the login widget.
For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Query Parameters

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

    Allowable values: [logo]

Form Parameters

  • The image file. The recommended size is 320x320 px. The maxmimum files size is 100kb.

Response

Status Code

  • No content. The service login widget logo was updated.

  • The tenantId, file type, or file size are invalid or missing. The file must be either a JPG or PNG that is less than 100kb.

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

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

No Sample Response

This method does not specify any sample responses.

Get the SAML metadata

Returns the SAML metadata required in order to integrate App ID with a SAML identity provider. For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Response

Status Code

  • An xml snippet that contains the metadata for using SAML as a service provider.

  • The tenantId parameter is missing or invalid.

  • Returned in case of internal server error.

Example responses

Get an email template

Returns the content of a custom email template or the default template in case it wasn't customized. For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

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

    Allowable values: [USER_VERIFICATION,RESET_PASSWORD,WELCOME,PASSWORD_CHANGED,MFA_VERIFICATION]

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

Response

Status Code

  • The email template data is returned as a JSON object. If the language template does not exist yet the english template (en) will be returned.

  • The tenantId or templateName are missing or invalid or language is not in the app localization configuration.

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

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

No Sample Response

This method does not specify any sample responses.

Update an email template

Updates the cloud directory email template.
For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

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

    Allowable values: [USER_VERIFICATION,RESET_PASSWORD,WELCOME,PASSWORD_CHANGED,MFA_VERIFICATION]

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

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

  • subject: The subject of the email.
  • html_body: Optional. The HTML body of the email.
  • plain_text_body: Optional. The text body of the email.
Response

Status Code

  • The email template properties is returned as a JSON object.

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

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

  • The tenantId or request body is missing or invalid.

  • The user is unauthorized.

  • The user has insufficient permissions.

No Sample Response

This method does not specify any sample responses.

Delete an email template

Delete the customized email template and reverts to App ID default template. For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

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

    Allowable values: [USER_VERIFICATION,RESET_PASSWORD,WELCOME,PASSWORD_CHANGED,MFA_VERIFICATION]

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

Response

Status Code

  • The template was deleted.

  • The tenantId is missing or invalid.

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

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

  • The template does not exist.

No Sample Response

This method does not specify any sample responses.

Get languages

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

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Response

Status Code

  • The localization data is returned as a JSON object.

  • The tenantId or languages are missing or invalid.

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

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

No Sample Response

This method does not specify any sample responses.

Update languages

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

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

User localization configuration. Available languages codes

Response

Status Code

  • 'No content. The localization configuration was updated.'

  • The tenantId or request body is missing or invalid.

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

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

No Sample Response

This method does not specify any sample responses.

Get sender details

Returns the sender details configuration that is used by Cloud Directory when sending emails For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Response

Status Code

  • The sender details configuration for a cloud directory email returned as a JSON object.

  • The tenantId parameter is missing or invalid or invalid request.

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

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

No Sample Response

This method does not specify any sample responses.

Update the sender details

Updates the sender details configuration that is used by Cloud Directory when sending emails For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

A JSON object that contains the sender details.

Response

Status Code

  • No content. The identity provider configuration was updated.

  • The tenantId or request body is missing or invalid.

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

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

No Sample Response

This method does not specify any sample responses.

Get action url

Get the custom url to redirect to when action is executed. For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

  • The type of the action. on_user_verified - the URL of your custom user verified page, on_reset_password - the URL of your custom reset password page.

    Allowable values: [on_user_verified,on_reset_password]

Response

Status Code

  • The action URL that is returned as a JSON object.

  • The tenantId or action parameters are invalid.

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

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

No Sample Response

This method does not specify any sample responses.

Update action url

Updates the custom url to redirect to when action is executed. For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

  • The type of the action. on_user_verified - the URL of your custom user verified page, on_reset_password - the URL of your custom reset password page.

    Allowable values: [on_user_verified,on_reset_password]

Form Parameters

  • The action URL.

Response

Status Code

  • The action url.

  • The tenantId or action parameters are invalid.

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

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

No Sample Response

This method does not specify any sample responses.

Delete action url

Delete the custom url to redirect to when action is executed. For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

  • The type of the action. on_user_verified - the URL of your custom user verified page, on_reset_password - the URL of your custom reset password page.

    Allowable values: [on_user_verified,on_reset_password]

Response

Status Code

  • No content. The action url was deleted.

  • The tenantId or action parameters are invalid.

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

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

  • The template does not exist.

No Sample Response

This method does not specify any sample responses.

Get password regex

Returns the regular expression used by App ID for password strength validation For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Response

Status Code

  • Returns a JSON object of defined regex expression rule for acceptable password and custom error message.

  • The tenantId is invalid.

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

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

No Sample Response

This method does not specify any sample responses.

Update password regex

Updates the regular expression used by App ID for password strength validation.
NOTE: Since the regualr expression is passed as a JSON string, special characters (such as forward slash) must be properly escaped. For example, the regular expression: "^[A-Za-z\d]$" should be passed as:
{
  "regex": "^[A-Za-z&\\d]
$",
  "error_message": "Must only contain letters and digits"
}


For more information, check out the docs

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

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

Response

Status Code

  • The password regex was updated.

  • The tenantId or password regex parameters are invalid.

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

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

No Sample Response

This method does not specify any sample responses.

Get custom email dispatcher configuration

Get the configuration of custom email dispatcher that is used by Cloud Directory when sending emails

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Response

Status Code

  • Return the email dispatcher configuration.

  • The tenantId is invalid.

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

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

No Sample Response

This method does not specify any sample responses.

Update custom email dispatcher configuration

You can define a custom email dispatcher by providing App ID with URL. The URL is called for sending emails. Optionally, you can determine a specific authorization method – either basic, such as a username and password, or a custom value.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

The Cloud Directory email dispatcher configuration, specified as a JSON object. If left blank, a default email vendor is used.

Response

Status Code

  • The email dispatcher was updated.

  • The tenantId or custom email dispatcher config are invalid.

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

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

No Sample Response

This method does not specify any sample responses.

Test the email dispatcher configuration

You can send a message to a specific email to test your configuration.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Form Parameters

  • The email address where you want to send your test message.

Response

Status Code

  • Returns the response status code and headers from the custom email dispatcher.

  • The tenantId or email value are invalid.

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

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

No Sample Response

This method does not specify any sample responses.

Test the MFA SMS dispatcher configuration

You can send a message to a specific phone number to test your MFA SMS configuration.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

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

Response

Status Code

  • Returns the response status code and headers from the SMS dispatcher.

  • The tenantId or SMS channel configuration is invalid.

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

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

No Sample Response

This method does not specify any sample responses.

Get APM configuration

Get the configuration of the advanced password management.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Response

Status Code

  • Return the advanced password management configuration.

  • The tenantId is invalid.

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

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

No Sample Response

This method does not specify any sample responses.

Update APM configuration

Updates the advanced password management configuration for the provided tenantId. By turning this on, any authentication event is also charged as advanced security event.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

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

Response

Status Code

  • The advanced password management configuration was updated.

  • The tenantId or advanced password management configuration are invalid.

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

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

No Sample Response

This method does not specify any sample responses.

Get channels

Returns all MFA channels registered with the App ID Instance.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Response

Status Code

  • Returns a JSON object of all the MFA channels registered with the App ID tenant

  • The tenantId is missing or invalid.

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

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

No Sample Response

This method does not specify any sample responses.

Get channel

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

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

  • The MFA channel.

    Allowable values: [email,nexmo]

Response

Status Code

  • Returns a specific channel registered with the App ID tenant as a JSON object

  • The tenantId is missing or invalid.

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

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

Example responses

Update channel

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

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

  • The MFA channel.

    Allowable values: [email,nexmo]

Update MFA channel payload.

Response

Status Code

  • A JSON object with the updated channel data

  • The tenantId or request body is missing or invalid.

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

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

  • The channel could not be found.

  • Returned in case of internal server error.

Example responses

Get MFA configuration

Returns MFA configuration registered with the App ID Instance.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Response

Status Code

  • Returns MFA configuration registered with the App ID tenant as a JSON object

  • The tenantId is missing or invalid.

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

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

No Sample Response

This method does not specify any sample responses.

Update MFA configuration

Update MFA configuration on the App ID instance.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Update MFA configuration payload.

Example:
Response

Status Code

  • A JSON object with the updated MFA configuration data

  • The tenantId or request body is missing or invalid.

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

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

  • Returned in case of internal server error.

No Sample Response

This method does not specify any sample responses.

Get Cloud Directory users

Get the list of Cloud Directory users For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Query Parameters

  • The first result in a set list of results.

  • The maximum number of results per page.

    Constraints: 0 ≤ value ≤ 100

  • Filter users by identity field.

Response

Status Code

  • The cloud directory users data is returned as a JSON object. Full user data can be found here: https://tools.ietf.org/html/rfc7643#section-8.2

  • The tenantId is missing or invalid.

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

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

No Sample Response

This method does not specify any sample responses.

Create a Cloud Directory user

Creates a new Cloud Directory user. For more information, check out the docs.
NOTE: Users added with this API will not receive a verification email.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Store cloud directory user data.

Response

Status Code

  • A JSON object with the new cloud directory user data. Full user data can be found here: https://tools.ietf.org/html/rfc7643#section-8.2

  • The tenantId or request body is missing or invalid.

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

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

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

No Sample Response

This method does not specify any sample responses.

Get a Cloud Directory user

Returns the requested Cloud Directory user object For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

  • The ID assigned to a user when they sign in by using cloud directory.

Response

Status Code

  • The updated cloud directory user data is returned as a JSON object. Full user data can be found here: https://tools.ietf.org/html/rfc7643#section-8.2

  • The tenantId or userId is missing or invalid.

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

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

  • The cloud directory user could not be found.

No Sample Response

This method does not specify any sample responses.

Update a Cloud Directory user

Updates an existing Cloud Directory user For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

  • The ID assigned to a user when they sign in by using cloud directory.

Update cloud directory user data.

Response

Status Code

  • The updated cloud directory user data is returned as a JSON object. Full user data can be found here: https://tools.ietf.org/html/rfc7643#section-8.2

  • The tenantId or request body is missing or invalid.

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

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

  • The cloud directory user could not be found.

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

No Sample Response

This method does not specify any sample responses.

Delete a cloud directory user

Deletes an existing Cloud Directory user. Note: This action cannot be undone For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

  • The ID assigned to a user when they sign in by using cloud directory.

Response

Status Code

  • The user was deleted from the cloud directory.

  • The tenantId is missing or invalid.

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

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

  • The cloud directory user could not be found.

No Sample Response

This method does not specify any sample responses.

Export Cloud Directory users

Exports Cloud Directory users with their profile attributes and hashed passwords For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Query Parameters

  • A custom string that will be use to encrypt and decrypt the users hashed password.

  • The first result in a set list of results.

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

    Constraints: value ≥ 0

Response

Status Code

  • Returns a list of the users in your cloud directory and their profiles. You can see up to 50 users per request.

  • The tenantId or userId is missing or invalid.

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

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

  • The cloud directory user could not be found.

No Sample Response

This method does not specify any sample responses.

Import Cloud Directory users

Imports Cloud Directory users list that was exported using the /export API For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Query Parameters

  • A custom string that will be use to encrypt and decrypt the users hashed password.

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

Response

Status Code

  • Import cloud directory users from another instance of App ID. The format for import is the same format in which the users are exported from the initial instance. You can add up to 50 users per request.

  • The tenantId or userId is missing or invalid.

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

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

  • The cloud directory user could not be found.

No Sample Response

This method does not specify any sample responses.

Sign up

Start the sign up process For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Query Parameters

  • Preferred language for resource. Format as described at RFC5646.

    Default: en

Store cloud directory user data.

Response

Status Code

  • A JSON object with the new Cloud Directory user data. Full user data can be found here: https://tools.ietf.org/html/rfc7643#section-8.2

  • The tenantId or request body is missing or invalid.

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

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

  • The email address already exist.

No Sample Response

This method does not specify any sample responses.

Get signup confirmation result

Returns the sign up confirmation result For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Form Parameters

  • The context that will be use to get the verification or forgot password confirmation result.

Response

Status Code

  • A JSON object with the sign up confirmation result

  • The tenantId or context is missing or invalid.

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

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

  • The context was not found.

Example responses

Forgot password

Starts the forgot password process. For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Query Parameters

  • Preferred language for resource. Format as described at RFC5646.

    Default: en

Form Parameters

Response

Status Code

  • A JSON object with the Cloud Directory user data. Full user data can be found here: https://tools.ietf.org/html/rfc7643#section-8.2

  • The tenantId or request body is missing or invalid.

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

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

  • User account not verified.

No Sample Response

This method does not specify any sample responses.

Forgot password confirmation result

Returns the forgot password flow confirmation result. For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Form Parameters

  • The context that will be use to get the verification or forgot password confirmation result.

Response

Status Code

  • A JSON object with the forgot password confirmation result

  • The tenantId or context is missing or invalid.

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

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

  • The context was not found.

Example responses

Change password

Changes the Cloud Directory user password. For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Query Parameters

  • Preferred language for resource. Format as described at RFC5646.

    Default: en

Form Parameters

  • The new password.

  • The Cloud Directory unique user Id.

  • The ip address the password changed from.

Response

Status Code

  • A JSON object with the Cloud Directory user data. Full user data can be found here: https://tools.ietf.org/html/rfc7643#section-8.2

  • The tenantId, uuid or newPassword is missing or invalid.

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

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

No Sample Response

This method does not specify any sample responses.

Resend user notifications

Resend user email notifications (e.g. resend user verification email) For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

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

    Allowable values: [USER_VERIFICATION,RESET_PASSWORD,WELCOME,PASSWORD_CHANGED]

Query Parameters

  • Preferred language for resource. Format as described at RFC5646.

    Default: en

Form Parameters

  • The Cloud Directory unique user Id.

Response

Status Code

  • The notification will be send

  • The tenantId or request body is missing or invalid.

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

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

  • User account not verified in case of template name is RESET_PASSOWRD.

  • User account already confirmed in case of template name is CONFIRMATION.

No Sample Response

This method does not specify any sample responses.

Search users

Returns list of users which match the given email/id. Either email or id should be given.
For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Query Parameters

  • Email (as retrieved from the Identity Provider).

  • The IDP specific user identifier.

Response

Status Code

  • Returns a JSON object contains an array of results

  • When tenantId is missing or invalid, or missing one of email / id

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

  • You are not authorized to perform this operation. Contact the service owner or admin to verify your permissions.

  • Returned in case of internal server error.

No Sample Response

This method does not specify any sample responses.

Pre-register a user profile

Build a new App ID user profile with custom attributes before a user's initial sign-in. For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

User configuration and attributes.

Response

Status Code

  • Returns the ID of the created user.

  • The tenantId, IdP type, idp identity id is missing or invalid.

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

  • You are not authorized to perform this operation. Contact the service owner or admin to verify your permissions.

  • User ID for the provided IdP already exists.

  • Returned in case of internal server error.

Example responses

Delete user

Deletes a user by id.
For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

  • The user's identifier ('subject' in identity token) You can search user in /users.

Response

Status Code

  • The user was deleted successfully.

  • The tenantId or id is missing or invalid.

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

  • You are not authorized to perform this operation. Contact the service owner or admin to verify your permissions.

  • User not found.

  • Returned in case of internal server error.

No Sample Response

This method does not specify any sample responses.

Revoke refresh token

Revokes all the refresh tokens issued for the given user.
For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

  • The user's identifier ('subject' in identity token) You can search user in /users.

Response

Status Code

  • No content. The users refresh token was revoked.

  • The tenantId or id is missing or invalid.

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

  • You are not authorized to perform this operation. Contact the service owner or admin to verify your permissions.

  • User not found.

  • Returned in case of internal server error.

No Sample Response

This method does not specify any sample responses.

Get user profile

Returns the profile of a given user For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

  • The user's identifier ('subject' in identity token) You can search user in /users.

Response

Status Code

  • Returns a JSON object of the user profile

  • The tenantId or id is missing or invalid.

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

  • You are not authorized to perform this operation. Contact the service owner or admin to verify your permissions.

  • User not found

  • Returned in case of internal server error.

Example responses

Update user profile

Updates a user profile For more information, check out the docs.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

  • The user's identifier ('subject' in identity token) You can search user in /users.

User's profile JSON. Only the 'attributes' field is accepted.

Response

Status Code

  • The updated user profile JSON.

  • The tenantId , id or request body is missing or invalid.

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

  • You are not authorized to perform this operation. Contact the service owner or admin to verify your permissions.

  • User not found

  • Returned in case of internal server error.

No Sample Response

This method does not specify any sample responses.

Get applications

Returns all applications registered with the App ID Instance.

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

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Response

Status Code

  • Returns a JSON object of all the applications registered with the App ID tenant

  • The tenantId is missing or invalid.

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

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

No Sample Response

This method does not specify any sample responses.

Create application

Register a new application with the App ID instance.

POST /management/v4/{tenantId}/applications
Request

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

Application registration payload. Application name cannot exceed 50 characters.

Response

Status Code

  • A JSON object with the new registered application data

  • The tenantId or request body is missing or invalid.

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

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

  • Returned in case of internal server error.

Example responses

Get application

Returns a specific application registered with the App ID Instance.

GET /management/v4/{tenantId}/applications/{id}
Request

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

  • The application clientId.

Response

Status Code

  • Returns a specific application registered with the App ID tenant as a JSON object

  • The tenantId is missing or invalid.

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

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

Example responses

Update application

Update an application registered with the App ID instance.

PUT /management/v4/{tenantId}/applications/{id}
Request

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

  • The application clientId.

Application registration payload. Application name cannot exceed 50 characters.

Response

Status Code

  • A JSON object with the updated application data

  • The tenantId or request body is missing or invalid.

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

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

  • The application could not be found.

  • Returned in case of internal server error.

Example responses

Delete application

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

DELETE /management/v4/{tenantId}/applications/{id}
Request

Path Parameters

  • The service tenantId. The tenantId can be found in the service credentials.

  • The application clientId.

Response

Status Code

  • The application was deleted.

  • The tenantId is missing or invalid.

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

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

  • The application could not be found.

No Sample Response

This method does not specify any sample responses.