IBM Cloud API Docs

Introduction

With IBM Cloud™ App ID, you can secure resources and add authentication, even when you don't have a lot of security experience. By requiring users to sign in to your app, you can store user data such as preferences or information from their public social profiles that you can use to customize each experience of your app.

Need some help getting started? Check out this video tutorial on working with the Management API.

Endpoint URLs

App ID supports region-specific endpoint URLs that you can use to interact with the service over public service endpoints. To make requests to the Management API, you supply the endpoint URL that corresponds with the location where your App ID service instance resides.

Endpoint URLs by location

  • Dallas: https://us-south.appid.cloud.ibm.com
  • Frankfurt: https://eu-de.appid.cloud.ibm.com
  • London: https://eu-gb.appid.cloud.ibm.com
  • Osaka: https://jp-osa.appid.cloud.ibm.com
  • Sao Paulo: https://br-sao.appid.cloud.ibm.com
  • Sydney: https://au-syd.appid.cloud.ibm.com
  • Tokyo: https://jp-tok.appid.cloud.ibm.com
  • Toronto: https://ca-tor.appid.cloud.ibm.com
  • Washington: https://us-east.appid.cloud.ibm.com

Base URL

https://{region}.appid.cloud.ibm.com

Authentication

This API uses token-based IBM Cloud® Identity and Access Management (IAM) authentication.

To work with the Management APIs, you need to provide a valid IAM token in each request to the service. You can generate an IAM token by first creating an IBM Cloud API key and then exchanging your API key for an IBM Cloud IAM token.

Don't have an API key? Try running ibmcloud iam oauth-tokens in the IBM Cloud Shell to quickly generate a personal access token.

To generate an access token from your API key, use the following cURL command.

curl -X POST \
  "https://iam.cloud.ibm.com/identity/token" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Accept: application/json' \
  --data-urlencode 'grant_type=urn:ibm:params:oauth:grant-type:apikey' \
  --data-urlencode 'apikey={api_key}'

Replace {api_key} with your IBM Cloud API key. To learn more, check out the IAM docs.

Example that uses IAM authentication

curl -X {request_method} "{base_url}/api/v1/{method_endpoint}" --header "Authorization: Bearer {IAM_token}"

Replace {IAM_token} with your IBM Cloud IAM access token.

Auditing

You can monitor API activity within your account by using the IBM Cloud Activity Tracker service. Whenever an API method is called, an event is generated that you can then track and audit from within Activity Tracker. The specific event type is listed for each individual method.

For more information about how to track App ID activity, see Auditing events for App ID.

Error handling

The App ID APIs use standard HTTP status codes to indicate whether a method completed successfully. HTTP response codes in the 2xx range indicate success. A response in the 4xx range is some sort of failure, and a response in the 5xx range usually indicates an internal system error.

Status code summary
Status code Description
200 OK Everything worked as expected.
201 OK Everything worked as expected. No content is returned.
400 Bad Request The request was unsuccessful, often due to a missing required parameter.
401 Unauthorized The parameters were valid but the request failed due insufficient permissions.
404 Not Found The requested resource doesn't exist.
409 Conflict The requested resource conflicts with an already existing resource.
410 Gone The requested resource was deleted and no longer exists.
429 Too Many Requests Too many requests hit the API too quickly.
500 Internal Server Error Something went wrong on App ID's end.

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

Methods

Get Facebook IDP configuration

Returns the Facebook identity provider configuration.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.idps

Auditing

Calling this method generates the following auditing event.

  • appid.idp-config.read

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. Learn more.

  • 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
  • {
      "isActive": true,
      "config": {
        "idpId": "facebook_appID",
        "secret": "facebook_appsecret"
      },
      "redirectURL": "https://us-south.appid.cloud.ibm.com/oauth/v4/39a37f57-a227-4bfe-a044-93b6e6060b61/Facebook/callback"
    }

Update Facebook IDP configuration

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.set.idps

Auditing

Calling this method generates the following auditing event.

  • appid.idp-config.update

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

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

Example responses
  • {
      "isActive": true,
      "config": {
        "idpId": "facebook_appID",
        "secret": "facebook_appsecret"
      }
    }

Get Google IDP configuration

Returns the Google identity provider configuration.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.idps

Auditing

Calling this method generates the following auditing event.

  • appid.idp-config.read

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. Learn more.

  • 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
  • {
      "isActive": true,
      "config": {
        "idpId": "google_appID",
        "secret": "google_appsecret"
      },
      "redirectURL": "https://us-south.appid.cloud.ibm.com/oauth/v4/39a37f57-a227-4bfe-a044-93b6e6060b61/Google/callback"
    }

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. Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.set.idps

Auditing

Calling this method generates the following auditing event.

  • appid.idp-config.update

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

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

Example responses
  • {
      "isActive": true,
      "config": {
        "idpId": "google_appID",
        "secret": "google_appsecret"
      }
    }

Get IBMid IDP configuration

Returns the IBMid identity provider configuration.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.idps

Auditing

Calling this method generates the following auditing event.

  • appid.idp-config.read

Request

Path Parameters

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

Response

Status Code

  • Returns a JSON object of the IBMid 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 IBMid IDP configuration

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.set.idps

Auditing

Calling this method generates the following auditing event.

  • appid.idp-config.update

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

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

Example responses
  • {
      "isActive": true,
      "config": {
        "idpId": "client_id",
        "secret": "client_secret",
        "preProd": false,
        "ciBased": true
      },
      "redirectURL": "https://example.com"
    }

Get Custom identity configuration

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.idps

Auditing

Calling this method generates the following auditing event.

  • appid.idp-config.read

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.

Example responses
  • {
      "isActive": true,
      "config": {
        "publicKey": "-----BEGIN RSA PUBLIC KEY-----u0mGFYvwLArEZNrK5SBwd...vPeBHF3Kq2xDfvhTBsl79j-----END RSA PUBLIC KEY-----"
      }
    }

Update Custom identity configuration

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.set.idps

Auditing

Calling this method generates the following auditing event.

  • appid.idp-config.update

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

Path Parameters

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

The identity provider configuration as a JSON object.

Examples:
View

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.

Example responses
  • {
      "isActive": true,
      "config": {
        "publicKey": "-----BEGIN RSA PUBLIC KEY-----u0mGFYvwLArEZNrK5SBwd...vPeBHF3Kq2xDfvhTBsl79j-----END RSA PUBLIC KEY-----"
      }
    }

Get Cloud Directory IDP configuration

Returns the Cloud Directory identity provider configuration. Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.idps

Auditing

Calling this method generates the following auditing event.

  • appid.idp-config.read

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.

Example responses
  • {
      "isActive": true,
      "config": {
        "selfServiceEnabled": true,
        "signupEnabled": true,
        "interactions": {
          "identityConfirmation": {
            "accessMode": "FULL",
            "methods": [
              "email"
            ]
          },
          "welcomeEnabled": false,
          "resetPasswordEnabled": false,
          "resetPasswordNotificationEnable": true
        },
        "identityField": "email"
      }
    }

Update Cloud Directory IDP configuration

Configure Cloud Directory to set up a single sign-on experience for your users. With Cloud Directory users can use their email and a password of their choice to log in to your applications. Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.set.idps

Auditing

Calling this method generates the following auditing event.

  • appid.idp-config.update

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

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.

Example responses
  • {
      "isActive": true,
      "config": {
        "selfServiceEnabled": true,
        "signupEnabled": true,
        "interactions": {
          "identityConfirmation": {
            "accessMode": "FULL",
            "methods": [
              "email"
            ]
          },
          "welcomeEnabled": false,
          "resetPasswordEnabled": false,
          "resetPasswordNotificationEnable": true
        },
        "identityField": "email"
      }
    }

Get SAML IDP configuration

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.idps

Auditing

Calling this method generates the following auditing event.

  • appid.idp-config.read

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.

Example responses
  • {
      "isActive": true,
      "config": {
        "entityID": "https://example.com/saml2/metadata/706634",
        "signInUrl": "https://example.com/saml2/sso-redirect/706634",
        "certificates": [
          "certificate-example-pem-format"
        ],
        "displayName": "my saml example",
        "authnContext": {
          "class": [
            "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport"
          ],
          "comparison": "exact"
        },
        "signRequest": false,
        "encryptResponse": false
      }
    }

Update SAML IDP configuration

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.set.idps

Auditing

Calling this method generates the following auditing event.

  • appid.idp-config.update

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

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.

Example responses
  • {
      "isActive": true,
      "config": {
        "entityID": "https://example.com/saml2/metadata/706634",
        "signInUrl": "https://example.com/saml2/sso-redirect/706634",
        "certificates": [
          "certificate-example-pem-format"
        ],
        "displayName": "my saml example",
        "authnContext": {
          "class": [
            "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport"
          ],
          "comparison": "exact"
        },
        "signRequest": false,
        "encryptResponse": false
      },
      "validation_data": {
        "certificates": [
          {
            "certificate_index": 0,
            "expiration_timestamp": 1674473996,
            "warning": "Your certificate will expire in 18 days."
          }
        ]
      }
    }

Get tokens configuration

Returns the token configuration. Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.tokens-config.read

Auditing

Calling this method generates the following auditing event.

  • appid.mgmt.get.tokens.configuration

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.

Example responses
  • {
      "idTokenClaims": [
        {
          "source": "attributes",
          "sourceClaim": "theme"
        }
      ],
      "accessTokenClaims": [
        {
          "source": "saml",
          "sourceClaim": "user_type",
          "destinationClaim": "type"
        }
      ],
      "access": {
        "expires_in": 3600
      },
      "refresh": {
        "expires_in": 2592000,
        "enabled": true
      },
      "anonymousAccess": {
        "expires_in": 2592000,
        "enabled": true
      }
    }

Update tokens configuration

Update the tokens' configuration to fine-tune the expiration times of access, id and refresh tokens, to enable/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. Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.set.tokens.configuration

Auditing

Calling this method generates the following auditing event.

  • appid.tokens-config.update

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

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.

Examples:
View

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.

Example responses
  • {
      "idTokenClaims": [
        {
          "source": "attributes",
          "sourceClaim": "theme"
        }
      ],
      "accessTokenClaims": [
        {
          "source": "saml",
          "sourceClaim": "user_type",
          "destinationClaim": "type"
        }
      ],
      "access": {
        "expires_in": 3600
      },
      "refresh": {
        "expires_in": 2592000,
        "enabled": true
      },
      "anonymousAccess": {
        "expires_in": 2592000,
        "enabled": true
      }
    }

Get redirect URIs

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.redirect.uris

Auditing

Calling this method generates the following auditing event.

  • appid.redirect-uris.read

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.

Example responses
  • {
      "redirectUris": [
        "https://example.com/oauth-callback"
      ]
    }

Update redirect URIs

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.set.redirect.uris

Auditing

Calling this method generates the following auditing event.

  • appid.redirect-uris.update

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

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. Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.user.profile.config

Auditing

Calling this method generates the following auditing event.

  • appid.is-profiles-active.read

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.

Example responses
  • {
      "isActive": false
    }

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. Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.set.user.profile.config

Auditing

Calling this method generates the following auditing event.

  • appid.is-profiles-active.update

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

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. Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.ui.config

Auditing

Calling this method generates the following auditing event.

  • appid.theme-color.read

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.

Example responses
  • {
      "tabTitle": "Login",
      "footnote": "Powered by App ID"
    }

Update widget texts

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.set.ui.config

Auditing

Calling this method generates the following auditing event.

  • appid.theme-text.update

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

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. Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.ui.config

Auditing

Calling this method generates the following auditing event.

  • appid.theme-color.read

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.

Example responses
  • {
      "headerColor": "#EEF2F5"
    }

Update widget colors

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.set.ui.config

Auditing

Calling this method generates the following auditing event.

  • appid.theme-color.update

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

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.

Delete widget logo

You can delete the image file shown in the login widget. Learn more.

DELETE /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]

Response

Status Code

  • The logo was deleted.

  • The tenantId or file type are missing.

  • 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 logo

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.ui.config

Auditing

Calling this method generates the following auditing event.

  • appid.media.read

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.

Example responses
  • {
      "image": "image-url"
    }

Update widget logo

You can update the image file shown in the login widget. Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.set.ui.config

Auditing

Calling this method generates the following auditing event.

  • appid.media.update

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. Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.saml.metadata

Auditing

Calling this method generates the following auditing event.

  • appid.saml-metadata.read

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
  • <SPSSODescriptor WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"><NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat><AssertionConsumerService index="1" isDefault="true" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://us-south.appid.cloud.ibm.com/saml2/v1/login-acs"/></SPSSODescriptor>

Get an email template

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.email.template

Auditing

Calling this method generates the following auditing event.

  • appid.email-template.read

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.

Example responses
  • {
      "subject": "Verify Your Email for %{user.displayName}",
      "html_body": "<h3>Hello %{user.displayName}</h3>\\n<p>Follow this link to verify your email address</p>\\n<p><a href='%{verify.link}'>%{verify.link}</a></p>\\n<p>If you didn't ask to verify this address, you can ignore this email</p>\\n<p>Thanks,</p>\\n<p>Your BMLand team</p>",
      "base64_encoded_html_body": "PGgzPkhlbGxvICV7dXNlci5kaXNwbGF5TmFtZX08L2gzPlxuPHA+Rm9sbG93IHRoaXMgbGluayB0byB2ZXJpZnkgeW91ciBlbWFpbCBhZGRyZXNzPC9wPlxuPHA+PGEgaHJlZj0nJXt2ZXJpZnkubGlua30nPiV7dmVyaWZ5Lmxpbmt9PC9hPjwvcD5cbjxwPklmIHlvdSBkaWRuJ3QgYXNrIHRvIHZlcmlmeSB0aGlzIGFkZHJlc3MsIHlvdSBjYW4gaWdub3JlIHRoaXMgZW1haWw8L3A+XG48cD5UaGFua3MsPC9wPlxuPHA+WW91ciBCTUxhbmQgdGVhbTwvcD4="
    }

Update an email template

Updates the Cloud Directory email template. Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.update.email.template

Auditing

Calling this method generates the following auditing event.

  • appid.email-template.update

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

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.
  • base64_encoded_html_body: Optional. The HTML body of the email encoded in Base64.
  • plain_text_body: Optional. The text body of the email.
Examples:
View

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.

Example responses
  • {
      "subject": "Verify Your Email for %{user.displayName}",
      "html_body": "<h3>Hello %{user.displayName}</h3>\\n<p>Follow this link to verify your email address</p>\\n<p><a href='%{verify.link}'>%{verify.link}</a></p>\\n<p>If you didn't ask to verify this address, you can ignore this email</p>\\n<p>Thanks,</p>\\n<p>Your BMLand team</p>",
      "base64_encoded_html_body": "PGgzPkhlbGxvICV7dXNlci5kaXNwbGF5TmFtZX08L2gzPlxuPHA+Rm9sbG93IHRoaXMgbGluayB0byB2ZXJpZnkgeW91ciBlbWFpbCBhZGRyZXNzPC9wPlxuPHA+PGEgaHJlZj0nJXt2ZXJpZnkubGlua30nPiV7dmVyaWZ5Lmxpbmt9PC9hPjwvcD5cbjxwPklmIHlvdSBkaWRuJ3QgYXNrIHRvIHZlcmlmeSB0aGlzIGFkZHJlc3MsIHlvdSBjYW4gaWdub3JlIHRoaXMgZW1haWw8L3A+XG48cD5UaGFua3MsPC9wPlxuPHA+WW91ciBCTUxhbmQgdGVhbTwvcD4="
    }
  • {
      "subject": "Verify Your Email for %{user.displayName}",
      "html_body": "<h3>Hello %{user.displayName}</h3>\\n<p>Follow this link to verify your email address</p>\\n<p><a href='%{verify.link}'>%{verify.link}</a></p>\\n<p>If you didn't ask to verify this address, you can ignore this email</p>\\n<p>Thanks,</p>\\n<p>Your BMLand team</p>",
      "base64_encoded_html_body": "PGgzPkhlbGxvICV7dXNlci5kaXNwbGF5TmFtZX08L2gzPlxuPHA+Rm9sbG93IHRoaXMgbGluayB0byB2ZXJpZnkgeW91ciBlbWFpbCBhZGRyZXNzPC9wPlxuPHA+PGEgaHJlZj0nJXt2ZXJpZnkubGlua30nPiV7dmVyaWZ5Lmxpbmt9PC9hPjwvcD5cbjxwPklmIHlvdSBkaWRuJ3QgYXNrIHRvIHZlcmlmeSB0aGlzIGFkZHJlc3MsIHlvdSBjYW4gaWdub3JlIHRoaXMgZW1haWw8L3A+XG48cD5UaGFua3MsPC9wPlxuPHA+WW91ciBCTUxhbmQgdGVhbTwvcD4="
    }

Delete an email template

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.delete.email.template

Auditing

Calling this method generates the following auditing event.

  • appid.email-template.delete

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.ui.config

Auditing

Calling this method generates the following auditing event.

  • appid.ui-languages.read

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.

Example responses
  • {
      "languages": [
        "en",
        "en-US",
        "fr-FR"
      ]
    }

Update languages

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.set.ui.config

Auditing

Calling this method generates the following auditing event.

  • appid.ui-languages.update

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

Path Parameters

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

User localization configuration. Available languages codes

Examples:
View

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. Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.sender.details.cd

Auditing

Calling this method generates the following auditing event.

  • appid.sender-details.read

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.

Example responses
  • {
      "senderDetails": {
        "from": {
          "name": "no-reply",
          "email": "no-reply@appid.cloud.net"
        },
        "reply_to": {
          "name": "Reply-to",
          "email": "reply-to@example.com"
        },
        "linkExpirationSec": 86400
      }
    }

Update the sender details

Updates the sender details configuration that is used by Cloud Directory when sending emails. Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.set.sender.details.cd

Auditing

Calling this method generates the following auditing event.

  • appid.sender-details.update

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

Path Parameters

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

A JSON object that contains the sender details.

Examples:
View

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. Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.cd.action.url

Auditing

Calling this method generates the following auditing event.

  • appid.action-url.read

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.

Example responses
  • {
      "actionUrl": "https://example.com/myCustomPage"
    }

Update action url

Updates the custom url to redirect to when action is executed. Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.update.cd.action.url

Auditing

Calling this method generates the following auditing event.

  • appid.action-url.update

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.

Example responses
  • {
      "actionUrl": "https://example.com/myCustomPage"
    }

Delete action url

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.del.cd.action.url

Auditing

Calling this method generates the following auditing event.

  • appid.action-url.delete

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. Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.cd.password.policy

Auditing

Calling this method generates the following auditing event.

  • appid.password-regex.read

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 escaped rule for acceptable password, base64 encoded regex expression 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.

Example responses
  • {
      "base64_encoded_regex": "LipbYS16XS4q",
      "error_message": "The password must contain at least 1 lowercase alphabetical character",
      "regex": ".*[a-z].*"
    }

Update password regex

Updates the regular expression used by App ID for password strength validation. For example, the regular expression: `"^[A-Za-z\d]*$"`` should be passed as:

{
  "base64_encoded_regex": "XltBLVphLXpcZF0qJA==",
  "error_message": "Must only contain letters and digits"
}

Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.update.cd.password.policy

Auditing

Calling this method generates the following auditing event.

  • appid.password-regex.update

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

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.

  • regex: Optional. The escaped regex expression rule for acceptable password.
  • base64_encoded_regex: Optional. The regex expression rule for acceptable password encoded in base64.
  • error_message: Custom error message.
Examples:
View

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.

Example responses
  • {
      "base64_encoded_regex": "LipbYS16XS4q",
      "error_message": "The password must contain at least 1 lowercase alphabetical character",
      "regex": ".*[a-z].*"
    }

Get email dispatcher configuration

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.update.cd.get.email.dispatcher

Auditing

Calling this method generates the following auditing event.

  • appid.email-dispatcher.read

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.

Example responses
  • {
      "provider": "sendgrid",
      "sendgrid": {
        "apiKey": "sendgridApiKey"
      },
      "custom": {
        "url": "https://custom_email_dispatcher.com/send",
        "authorization": {
          "type": "value",
          "value": "verySecureSecret"
        }
      }
    }

Update email dispatcher configuration

App ID allows you to use your own email provider. 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. Optionally, 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 will be used.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.update.cd.set.email.dispatcher

Auditing

Calling this method generates the following auditing event.

  • appid.email-dispatcher.update

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

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.

Examples:
View

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.

Example responses
  • {
      "provider": "sendgrid",
      "sendgrid": {
        "apiKey": "sendgridApiKey"
      },
      "custom": {
        "url": "https://custom_email_dispatcher.com/send",
        "authorization": {
          "type": "value",
          "value": "verySecureSecret"
        }
      }
    }

Test the email provider configuration

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.update.cd.post.email.dispatcher.test

Auditing

Calling this method generates the following auditing event.

  • appid.email-settings-test.send

Request

Path Parameters

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

Email dispatcher settings, specified as a JSON object.

Examples:
View

Response

Status Code

  • Returns the response status code and additional information from the email provider in case of failure.

  • The tenantId or 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.

Example responses
  • {
      "success": true,
      "dispatcherStatusCode": 202
    }

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.update.cd.post.email.dispatcher.test

Auditing

Calling this method generates the following auditing event.

  • appid.email-dispatcher-test.send

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.

Example responses
  • {
      "statusCode": 400,
      "headers": {
        "server": "nginx",
        "date": "Tue, 24 Jul 2018 09:50:25 GMT",
        "content-type": "application/json",
        "access-control-allow-headers": "Authorization, Content-Type"
      }
    }

Test the MFA SMS dispatcher configuration

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.cd.post.sms.dispatcher.test

Auditing

Calling this method generates the following auditing event.

  • appid.sms-dispatcher-test.send

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

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.

Example responses
  • {
      "confirmationCode": 979469,
      "phoneNumber": "+1-999-999-9999"
    }

Get APM configuration

Get the configuration of the advanced password management.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.advanced.password.management

Auditing

Calling this method generates the following auditing event.

  • appid.advanced-password-management.read

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.

Example responses
  • {
      "advancedPasswordManagement": {
        "enabled": true,
        "passwordReuse": {
          "enabled": true,
          "config": {
            "maxPasswordReuse": 8
          }
        },
        "preventPasswordWithUsername": {
          "enabled": true
        },
        "passwordExpiration": {
          "enabled": true,
          "config": {
            "daysToExpire": 30
          }
        },
        "lockOutPolicy": {
          "enabled": true,
          "config": {
            "lockOutTimeSec": 1800,
            "numOfAttempts": 3
          }
        },
        "minPasswordChangeInterval": {
          "enabled": true,
          "config": {
            "minHoursToChangePassword": 0
          }
        }
      }
    }

Update APM configuration

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.set.advanced.password.management

Auditing

Calling this method generates the following auditing event.

  • appid.advanced-password-management.update

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

Path Parameters

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

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

Examples:
View

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.

Example responses
  • {
      "advancedPasswordManagement": {
        "enabled": true,
        "passwordReuse": {
          "enabled": true,
          "config": {
            "maxPasswordReuse": 8
          }
        },
        "preventPasswordWithUsername": {
          "enabled": true
        },
        "passwordExpiration": {
          "enabled": true,
          "config": {
            "daysToExpire": 30
          }
        },
        "lockOutPolicy": {
          "enabled": true,
          "config": {
            "lockOutTimeSec": 1800,
            "numOfAttempts": 3
          }
        },
        "minPasswordChangeInterval": {
          "enabled": true,
          "config": {
            "minHoursToChangePassword": 0
          }
        }
      }
    }

Get tenant audit status

Returns a JSON object containing the auditing status of the tenant.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.capture.runtime.activity

Auditing

Calling this method generates the following auditing event.

  • appid.capture-runtime-activity.read

Request

Path Parameters

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

Response

Status Code

  • Returns a JSON object containing the auditing status of the 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.

Example responses
  • {
      "isActive": true
    }

Update tenant audit status

Capture app user sign-in, sign-up and other runtime events in Activity Tracker for you to search, analyze and report. By turning this On, any authentication event is also charged as advanced security event. Activity Tracker is available in select regions. Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.update.capture.runtime.activity

Auditing

Calling this method generates the following auditing event.

  • appid.capture-runtime-activity.update

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

Path Parameters

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

The new audit status, specified as a JSON object.

Response

Status Code

  • The tenant 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 channels

Returns all MFA channels registered with the App ID Instance.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.mfa.channels

Auditing

Calling this method generates the following auditing event.

  • appid.mfa-channels.read

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.

Example responses
  • {
      "channels": [
        {
          "isActive": true,
          "type": "email"
        },
        {
          "isActive": false,
          "type": "sms",
          "config": {
            "key": "key",
            "secret": "secret",
            "from": 1234567890,
            "provider": "nexmo"
          }
        }
      ]
    }

Get channel

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.mfa.channel

Auditing

Calling this method generates the following auditing event.

  • appid.mfa-channel.read

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
  • [
      {
        "isActive": false,
        "type": "sms",
        "config": {
          "key": "key",
          "secret": "secret",
          "from": "1234567890",
          "provider": "nexmo"
        }
      }
    ]

Update channel

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.update.mfa.channel

Auditing

Calling this method generates the following auditing event.

  • appid.mfa-channel.update

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

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
  • [
      {
        "isActive": false,
        "type": "sms",
        "config": {
          "key": "key",
          "secret": "secret",
          "from": "1234567890",
          "provider": "nexmo"
        }
      }
    ]

Get an extension configuration

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.webhook.config

Auditing

Calling this method generates the following auditing event.

  • appid.mfa-extension.read

Request

Path Parameters

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

  • The name of the extension.

    Allowable values: [premfa,postmfa]

Response

Status Code

  • A JSON object that contains the extension configuration.

  • The tenant ID or request body is either missing or invalid.

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

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

  • Internal server error. Try again in a few minutes.

Example responses
  • {
      "isActive": true,
      "config": {
        "url": "https://example.com/extension",
        "headers": {
          "authorization": "Bearer <token>"
        }
      }
    }

Update an extension configuration

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.update.webhook.config

Auditing

Calling this method generates the following auditing event.

  • appid.mfa-extension.update

Request

Path Parameters

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

  • The name of the extension.

    Allowable values: [premfa,postmfa]

Update extension configuration payload.

Examples:
View

Response

Status Code

  • A JSON object that contains either true or false, depending on your configuration.

  • The tenant ID or request body is either missing or invalid.

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

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

  • Internal server error. Try again in a few minutes.

Example responses
  • {
      "isActive": true,
      "config": {
        "url": "https://example.com/extension",
        "headers": {
          "authorization": "Bearer <token>"
        }
      }
    }

Enable or disable an extension

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.update.webhook.active

Auditing

Calling this method generates the following auditing event.

  • appid.is-mfa-extension-active.update

Request

Path Parameters

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

  • The name of the extension.

    Allowable values: [premfa,postmfa]

Update extension enabled.

Examples:
View

Response

Status Code

  • A JSON object that contains either true or false, depending on your configuration.

  • The tenant ID or request body is either missing or invalid.

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

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

  • Internal server error. Try again in a few minutes.

Example responses
  • {
      "isActive": true
    }

Test the extension configuration

Test an extension configuration. Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.test.webhook.config

Auditing

Calling this method generates the following auditing event.

  • appid.mfa-extension-test.send

Request

Path Parameters

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

  • The name of the extension.

    Allowable values: [premfa,postmfa]

Response

Status Code

  • The response status code as well as the response body and headers from the extension's URL.

  • The tenant ID or extension name are missing or invalid.

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

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

Example responses
  • {
      "statusCode": 200,
      "responseBody": {
        "skipMfa": true
      },
      "responseHeaders": {
        "content-type": "application/json",
        "date": "Tue, 24 Jul 2018 09:50:25 GMT"
      }
    }

Get MFA configuration

Returns MFA configuration registered with the App ID Instance.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.mfa.config

Auditing

Calling this method generates the following auditing event.

  • appid.mfa.read

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.

Example responses
  • {
      "isActive": true
    }

Update MFA configuration

Update MFA configuration on the App ID instance.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.update.mfa.config

Auditing

Calling this method generates the following auditing event.

  • appid.mfa.update

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

Path Parameters

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

Update MFA configuration payload.

Examples:
View

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.

Example responses
  • {
      "isActive": true
    }

Get SSO configuration

Returns SSO configuration registered with the App ID Instance.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.sso.config

Auditing

Calling this method generates the following auditing event.

  • appid.sso.read

Request

Path Parameters

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

Response

Status Code

  • Returns SSO 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.

Example responses
  • {
      "isActive": true,
      "inactivityTimeoutSeconds": 86400,
      "logoutRedirectUris": [
        "http://localhost:3000/logout-callback"
      ]
    }

Update SSO configuration

Update SSO configuration on the App ID instance.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.update.sso.config

Auditing

Calling this method generates the following auditing event.

  • appid.sso.update

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

Path Parameters

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

Update SSO configuration payload.

Response

Status Code

  • A JSON object with the updated SSO 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.

Example responses
  • {
      "isActive": true,
      "inactivityTimeoutSeconds": 86400,
      "logoutRedirectUris": [
        "http://localhost:3000/logout-callback"
      ]
    }

Get the rate limit configuration

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.cd.rate.config

Auditing

Calling this method generates the following auditing event.

  • appid.rate-limit.read

Request

Path Parameters

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

Response

Status Code

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

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

Example responses
  • {
      "signUpLimitPerMinute": 50,
      "signInLimitPerMinute": 60
    }

Update the rate limit configuration

Update the rate limit configuration on the App ID instance.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.update.cd.rate.config

Auditing

Calling this method generates the following auditing event.

  • appid.rate-limit.update

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

Path Parameters

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

Update rate limit configuration payload.

Response

Status Code

  • A JSON object with the updated rate limit 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.

Example responses
  • {
      "signUpLimitPerMinute": 50,
      "signInLimitPerMinute": 60
    }

Sign up

Start the sign up process Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.cd.sign.up

Auditing

Calling this method generates the following auditing event.

  • appid.self-sign-up.start

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

Path Parameters

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

Query Parameters

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

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

Example responses
  • {
      "displayName": "John Doe",
      "active": true,
      "emails": [
        {
          "value": "johndoe@example.com",
          "primary": true
        }
      ],
      "meta": {
        "created": "2019-05-29T12:45:30.671Z",
        "lastModified": "2019-05-29T12:45:30.671Z",
        "resourceType": "User"
      },
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "name": {
        "givenName": "John",
        "familyName": "Doe",
        "formatted": "John Doe"
      },
      "id": "66ad3522-2251-4531-abff-3e3aad66b650"
    }

Get signup confirmation result

Returns the sign up confirmation result. Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.cd.sign.up.result

Auditing

Calling this method generates the following auditing event.

  • appid.sign-up-result.read

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
  • {
      "success": true,
      "uuid": "773f85b4-72f4-480d-aca8-755f517c4508"
    }
  • {
      "errorCode": "NOT_FOUND",
      "message": "context was not found"
    }

Forgot password

Starts the forgot password process. Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.cd.forgot.password

Auditing

Calling this method generates the following auditing event.

  • appid.self-forgot-password.start

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 user identitier - email or username based on the identityField property in Cloud Directory configuration.

    Possible values: length ≤ 200

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.

Example responses
  • {
      "displayName": "John Doe",
      "active": true,
      "emails": [
        {
          "value": "johndoe@example.com",
          "primary": true
        }
      ],
      "meta": {
        "created": "2019-05-29T12:45:30.671Z",
        "lastModified": "2019-05-29T12:45:30.671Z",
        "resourceType": "User"
      },
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "name": {
        "givenName": "John",
        "familyName": "Doe",
        "formatted": "John Doe"
      },
      "id": "66ad3522-2251-4531-abff-3e3aad66b650"
    }

Forgot password confirmation result

Returns the forgot password flow confirmation result. Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.cd.forgot.password.result

Auditing

Calling this method generates the following auditing event.

  • appid.forgot-password-result.read

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
  • {
      "success": true,
      "uuid": "773f85b4-72f4-480d-aca8-755f517c4508"
    }
  • {
      "errorCode": "NOT_FOUND",
      "message": "context was not found"
    }

Change password

Changes the Cloud Directory user password. Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.cd.change.password

Auditing

Calling this method generates the following auditing event.

  • appid.user-password.update

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.

Example responses
  • {
      "displayName": "John Doe",
      "active": true,
      "emails": [
        {
          "value": "johndoe@example.com",
          "primary": true
        }
      ],
      "meta": {
        "created": "2019-05-29T12:45:30.671Z",
        "lastModified": "2019-05-29T12:45:30.671Z",
        "resourceType": "User"
      },
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "name": {
        "givenName": "John",
        "familyName": "Doe",
        "formatted": "John Doe"
      },
      "id": "66ad3522-2251-4531-abff-3e3aad66b650"
    }

Resend user notifications

Resend user email notifications (e.g. resend user verification email). Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.resend.notification.cd

Auditing

Calling this method generates the following auditing event.

  • appid.resend-notification.send

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.

Example responses
  • {
      "message": "Email is queued to be delivered."
    }

Delete Cloud Directory user and profile

Deletes an existing Cloud Directory user and the profile related to it. Learn more.

Note: This action cannot be undone.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.remove.cd.user

Auditing

Calling this method generates the following auditing event.

  • appid.user.delete

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 and profile were deleted.

  • Invalid tenantId/userId.

  • 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 recent activity

This endpoint is deprecated. Use Get recent activity instead.

GET /management/v4/{tenantId}/recent_authentications

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.recent.activities

Auditing

Calling this method generates the following auditing event.

  • appid.recent-activity.read

Request

Path Parameters

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

Response

Status Code

  • An array of recent activity 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 permissions.

No Sample Response

This method does not specify any sample responses.

Get recent activity

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

GET /management/v4/{tenantId}/recent_authentications_hidden

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.recent.activities

Auditing

Calling this method generates the following auditing event.

  • appid.recent-activity.read

Request

Path Parameters

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

Response

Status Code

  • An object that contains an array of recent activity.

  • 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 permissions.

No Sample Response

This method does not specify any sample responses.

Search users

Returns list of users, if given email/id returns only users which match the email/id - not including anonymous profiles. Learn more.

GET /management/v4/{tenantId}/users

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.profiles

Auditing

Calling this method generates the following auditing event.

  • appid.users.read

Request

Path Parameters

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

Query Parameters

  • display user data.

    Allowable values: [index,full]

  • Email (as retrieved from the Identity Provider).

  • The IDP specific user identifier.

  • The first result in a set list of results.

  • The maximum number of results per page.

    Possible values: 0 ≤ value ≤ 100

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.

Example responses
  • {
      "totalResults": 7,
      "itemsPerPage": 3,
      "requestOptions": {
        "startIndex": 5,
        "count": 5
      },
      "users": [
        {
          "idp": "cloud_directory",
          "id": "e782661a-efdb-4540-9ed8-d6a3e26713ca",
          "email": "your@mail.com"
        },
        {
          "idp": "facebook",
          "id": "d6f32b32-90d9-4d60-82f2-f503bc244174",
          "email": "your@mail.com"
        },
        {
          "idp": "google",
          "id": "238c75c4-38ea-4de8-b5d4-338744d83b0f",
          "email": "your@mail.com"
        }
      ]
    }

Pre-register a user profile

Create a profile for a user that you know needs access to your app before they sign in to your app for the first time. Learn more.

POST /management/v4/{tenantId}/users

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.nominate.user

Auditing

Calling this method generates the following auditing event.

  • appid.users.create

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

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
  • {
      "id": "111c22c3-38ea-4de8-b5d4-338744d83b0f"
    }

Export user profiles

Exports App ID user profiles, not including Cloud Directory and anonymous users.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.export.profiles

Auditing

Calling this method generates the following auditing event.

  • appid.users.get

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.

    Possible values: 0 ≤ value ≤ 100

Response

Status Code

  • Returns a list of the App ID user profiles. You can see up to 50 users per request.

  • The tenantId 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.

  • The tenantId is not found.

Example responses
  • {
      "itemsPerPage": 2,
      "totalResults": 2,
      "requestOptions": {},
      "users": [
        {
          "id": "7ae804f3-0ed3-45f0-bc6b-1c6af868e6d6",
          "name": "App ID Google User profile",
          "email": "your@mail.com",
          "identities": [
            {
              "provider": "google",
              "id": "105646725068605084546",
              "idpUserInfo": {
                "id": "105646725068605084546",
                "email": "your@mail.com",
                "picture": "profilePic.jpg"
              }
            }
          ],
          "attributes": {
            "points": 150
          },
          "roles": []
        },
        {
          "id": "1439d777-185d-4be1-8f4a-c4e8142b87ea",
          "name": "App ID Facebook User profile",
          "email": "mail@mail.com",
          "identities": [
            {
              "provider": "facebook",
              "id": "100195207128541",
              "picture": {
                "data": {
                  "height": 50,
                  "width": 50,
                  "url": "https://profilePic.com"
                }
              },
              "first_name": "AppID",
              "last_name": "Development"
            }
          ],
          "attributes": {
            "points": 250
          },
          "roles": [
            "adult",
            "child"
          ]
        }
      ]
    }

Import user profiles

Imports App ID user profiles, not including Cloud Directory and anonymous users.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.import.profiles

Auditing

Calling this method generates the following auditing event.

  • appid.users.import

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

Path Parameters

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

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

Examples:
View

Response

Status Code

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

  • The tenantId 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.

  • The tenantId is not found.

Example responses
  • {
      "added": 30,
      "failed": 1,
      "failReasons": [
        {
          "originalId": "773f85b4-72f4-480d-aca8-755f517c4508",
          "idp": "facebook",
          "error": {
            "message": "The user already exists."
          }
        }
      ]
    }

Delete user

Deletes a user by id. Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.delete.profile

Auditing

Calling this method generates the following auditing event.

  • appid.user.delete

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 users by using the Search users API.

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. Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.revoke.refresh.token

Auditing

Calling this method generates the following auditing event.

  • appid.refresh-token.revoke

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

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 users by using the Search users API.

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. Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.profile

Auditing

Calling this method generates the following auditing event.

  • appid.user-profile.read

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 users by using the Search users API.

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
  • {
      "id": "111c22c3-38ea-4de8-b5d4-338744d83b0f",
      "name": "John Doe",
      "email": "johndoe@gmail.com",
      "picture": "https://lh5.googleusercontent.com/-dddddddQ/AAAAAAAAAAI/AAAAAAAAAAA/jondohw/photo.jpg",
      "gender": "male",
      "identities": [
        {
          "provider": "google",
          "id": "12341234123412341234",
          "idpUserInfo": {
            "id": "12341234123412341234",
            "email": "johndoe@gmail.com",
            "verified_email": true,
            "name": "John Doe",
            "given_name": "John",
            "family_name": "Doe",
            "link": "https://plus.google.com/12341234123412341234",
            "picture": "https://lh5.googleusercontent.com/-dddddddQ/AAAAAAAAAAI/AAAAAAAAAAA/jondohw/photo.jpg",
            "gender": "male",
            "idpType": "google"
          }
        }
      ],
      "attributes": {
        "points": "150"
      }
    }

Update user profile

Updates a user profile. Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.update.profile

Auditing

Calling this method generates the following auditing event.

  • appid.user-profile.update

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

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 users by using the Search users API.

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.

Example responses
  • {
      "id": "111c22c3-38ea-4de8-b5d4-338744d83b0f",
      "name": "John Doe",
      "email": "johndoe@gmail.com",
      "picture": "https://lh5.googleusercontent.com/-dddddddQ/AAAAAAAAAAI/AAAAAAAAAAA/jondohw/photo.jpg",
      "gender": "male",
      "identities": [
        {
          "provider": "google",
          "id": "12341234123412341234",
          "idpUserInfo": {
            "id": "12341234123412341234",
            "email": "johndoe@gmail.com",
            "verified_email": true,
            "name": "John Doe",
            "given_name": "John",
            "family_name": "Doe",
            "link": "https://plus.google.com/12341234123412341234",
            "picture": "https://lh5.googleusercontent.com/-dddddddQ/AAAAAAAAAAI/AAAAAAAAAAA/jondohw/photo.jpg",
            "gender": "male",
            "idpType": "google"
          }
        }
      ],
      "attributes": {
        "points": "150"
      }
    }

Get a user's roles

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.user.roles

Auditing

Calling this method generates the following auditing event.

  • appid.user-roles.read

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 users by using the Search users API.

Response

Status Code

  • The list of roles is returned as a JSON object.

  • The tenant ID or user ID are missing or invalid.

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

  • You have insufficient permissions. Contact your administrator to verify your permissions.

  • The user wasn't found.

No Sample Response

This method does not specify any sample responses.

Update a user's roles

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.update.user.roles

Auditing

Calling this method generates the following auditing event.

  • appid.user-roles.update

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

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 users by using the Search users API.

A JSON array of roles. The Array can have either names or IDs but not both.

Response

Status Code

  • The role is successfully associated with the user.

  • The tenant ID or user ID are missing or invalid.

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

  • You have insufficient permissions. Contact your administrator to verify your permissions.

  • One or more of the roles that you want to assign was not found. List all of your available roles by calling the /roles API.

No Sample Response

This method does not specify any sample responses.

View all roles

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

GET /management/v4/{tenantId}/roles

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.role

Auditing

Calling this method generates the following auditing event.

  • appid.roles.read

Request

Path Parameters

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

Response

Status Code

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

  • The tenant ID or user ID is missing or invalid.

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

  • You have insufficient permissions. Contact your administrator to verify your permissions.

No Sample Response

This method does not specify any sample responses.

Create a role

Create a new role for a registered application.

POST /management/v4/{tenantId}/roles

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.add.role

Auditing

Calling this method generates the following auditing event.

  • appid.roles.create

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

Path Parameters

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

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.

Response

Status Code

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

  • The payload is missing or invalid.

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

  • You have insufficient permissions. Contact your administrator to verify your permissions.

  • The role already exists. Choose a new name or update your existing role.

No Sample Response

This method does not specify any sample responses.

View a specific role

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.role

Auditing

Calling this method generates the following auditing event.

  • appid.role.read

Request

Path Parameters

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

  • The role identifier.

Response

Status Code

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

  • The tenant or user ID is missing or invalid.

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

  • You have insufficient permissions. Contact your administrator to verify your permissions.

  • The role couldn't be found. Verify your role ID by listing all of the roles that are associated with your application.

No Sample Response

This method does not specify any sample responses.

Update a role

Update an existing role.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.update.role

Auditing

Calling this method generates the following auditing event.

  • appid.role.update

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

Path Parameters

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

  • The role identifier.

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.

Response

Status Code

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

  • The payload is missing or invalid.

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

  • You have insufficient permissions. Contact your administrator to verify your permissions.

  • The role couldn't be found. Verify your role ID by listing all of the roles that are associated with your application.

No Sample Response

This method does not specify any sample responses.

Delete a role

Delete an existing role.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.delete.role

Auditing

Calling this method generates the following auditing event.

  • appid.role.delete

Request

Path Parameters

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

  • The role identifier.

Response

Status Code

  • Delete request has been accepted.

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

  • You have insufficient permissions. Contact your administrator to verify your permissions.

No Sample Response

This method does not specify any sample responses.

Get applications

Returns all applications registered with the App ID Instance.

GET /management/v4/{tenantId}/applications

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.application

Auditing

Calling this method generates the following auditing event.

  • appid.applications.read

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.

Example responses
  • {
      "clientId": "111c22c3-38ea-4de8-b5d4-338744d83b0f",
      "tenantId": "39a37f57-a227-4bfe-a044-93b6e6060b61",
      "secret": "ZmE5ZDQ5ODctMmU1ZS00OGRiLWExZDMtZTA2MjkyZTc4MDB1",
      "name": "IBMCloudApp",
      "oAuthServerUrl": "https://us-south.appid.cloud.ibm.com/oauth/v4/39a37f57-a227-4bfe-a044-93b6e6060b61",
      "type": "regularwebapp"
    }

Create application

Register a new application with the App ID instance.

POST /management/v4/{tenantId}/applications

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.add.application

Auditing

Calling this method generates the following auditing event.

  • appid.applications.create

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

Path Parameters

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

Application registration payload. Application name cannot exceed 50 characters.

Examples:
View

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
  • {
      "clientId": "111c22c3-38ea-4de8-b5d4-338744d83b0f",
      "tenantId": "39a37f57-a227-4bfe-a044-93b6e6060b61",
      "secret": "ZmE5ZDQ5ODctMmU1ZS00OGRiLWExZDMtZTA2MjkyZTc4MDB1",
      "name": "IBMCloudApp",
      "oAuthServerUrl": "https://us-south.appid.cloud.ibm.com/oauth/v4/39a37f57-a227-4bfe-a044-93b6e6060b61",
      "type": "regularwebapp"
    }

Get application

Returns a specific application registered with the App ID Instance.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.application

Auditing

Calling this method generates the following auditing event.

  • appid.application.read

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
  • {
      "clientId": "111c22c3-38ea-4de8-b5d4-338744d83b0f",
      "tenantId": "39a37f57-a227-4bfe-a044-93b6e6060b61",
      "secret": "ZmE5ZDQ5ODctMmU1ZS00OGRiLWExZDMtZTA2MjkyZTc4MDB1",
      "name": "IBMCloudApp",
      "oAuthServerUrl": "https://us-south.appid.cloud.ibm.com/oauth/v4/39a37f57-a227-4bfe-a044-93b6e6060b61",
      "type": "regularwebapp"
    }

Update application

Update an application registered with the App ID instance.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.update.application

Auditing

Calling this method generates the following auditing event.

  • appid.application.update

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

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.

Examples:
View

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
  • {
      "clientId": "111c22c3-38ea-4de8-b5d4-338744d83b0f",
      "tenantId": "39a37f57-a227-4bfe-a044-93b6e6060b61",
      "secret": "ZmE5ZDQ5ODctMmU1ZS00OGRiLWExZDMtZTA2MjkyZTc4MDB1",
      "name": "IBMCloudApp",
      "oAuthServerUrl": "https://us-south.appid.cloud.ibm.com/oauth/v4/39a37f57-a227-4bfe-a044-93b6e6060b61",
      "type": "regularwebapp"
    }

Delete application

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.delete.application

Auditing

Calling this method generates the following auditing event.

  • appid.application.delete

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.

Get application scopes

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

Auditing

Calling this method generates the following auditing event.

Request

Path Parameters

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

  • The application clientId.

Response

Status Code

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

  • The tenant or client ID is missing or invalid.

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

  • You have insufficient permissions. Contact your administrator to verify your permissions.

No Sample Response

This method does not specify any sample responses.

Add application scope

Update the scopes for a registered application.

Important: Removing a scope from an array deletes it from any roles that it is associated with and the action cannot be undone.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

Auditing

Calling this method generates the following auditing event.

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

Path Parameters

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

  • The application clientId.

Response

Status Code

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

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

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

  • You have insufficient permissions. Contact your administrator to verify your permissions.

  • The application can not be found.

No Sample Response

This method does not specify any sample responses.

Get application roles

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

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

Auditing

Calling this method generates the following auditing event.

Request

Path Parameters

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

  • The application clientId.

Response

Status Code

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

  • The tenant or client ID is missing or invalid.

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

  • You have insufficient permissions. Contact your administrator to verify your permissions.

No Sample Response

This method does not specify any sample responses.

Add application role

Update the roles for a registered application.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

Auditing

Calling this method generates the following auditing event.

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

Path Parameters

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

  • The application clientId.

A JSON array of roles. The Array can have either names or IDs but not both.

Response

Status Code

  • The role is successfully associated with the application.

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

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

  • You have insufficient permissions. Contact your administrator to verify your permissions.

  • The application can not be found.

No Sample Response

This method does not specify any sample responses.

Get Cloud Directory users

Get the list of Cloud Directory users. Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.cd.users

Auditing

Calling this method generates the following auditing event.

  • appid.cloud-directory-users.read

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.

    Possible values: 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.

Example responses
  • {
      "totalResults": 2,
      "itemsPerPage": 2,
      "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
      ],
      "Resources": [
        {
          "displayName": "John Doe",
          "active": true,
          "emails": [
            {
              "value": "johndoe@example.com",
              "primary": true
            }
          ],
          "meta": {
            "created": "2019-05-29T12:45:30.671Z",
            "lastModified": "2019-05-29T12:45:30.671Z",
            "resourceType": "User"
          },
          "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:User"
          ],
          "name": {
            "givenName": "John",
            "familyName": "Doe",
            "formatted": "John Doe"
          },
          "id": "66ad3522-2251-4531-abff-3e3aad66b650"
        },
        {
          "displayName": "Jane Doe",
          "active": true,
          "emails": [
            {
              "value": "jane@example.com",
              "primary": true
            }
          ],
          "meta": {
            "created": "2019-05-29T12:47:20.509Z",
            "lastModified": "2019-05-29T12:47:20.509Z",
            "resourceType": "User"
          },
          "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:User"
          ],
          "name": {
            "givenName": "Jane",
            "familyName": "Doe",
            "formatted": "Jane Doe"
          },
          "id": "e403878c-3ab5-4e99-8953-bb57b05387d8"
        }
      ]
    }

Create a Cloud Directory user

Create a new record for Cloud Directory (no verification email is sent, and no profile is created).

To create a new Cloud Directory user, use the Sign up API. Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.add.cd.user

Auditing

Calling this method generates the following auditing event.

  • appid.cloud-directory-users.create

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

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.

Example responses
  • {
      "displayName": "John Doe",
      "active": true,
      "emails": [
        {
          "value": "johndoe@example.com",
          "primary": true
        }
      ],
      "meta": {
        "created": "2019-05-29T12:45:30.671Z",
        "lastModified": "2019-05-29T12:45:30.671Z",
        "resourceType": "User"
      },
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "name": {
        "givenName": "John",
        "familyName": "Doe",
        "formatted": "John Doe"
      },
      "id": "66ad3522-2251-4531-abff-3e3aad66b650"
    }

Get a Cloud Directory user

Returns the requested Cloud Directory user object. Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.cd.users

Auditing

Calling this method generates the following auditing event.

  • appid.cloud-directory-user.read

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.

Example responses
  • {
      "displayName": "John Doe",
      "active": true,
      "emails": [
        {
          "value": "johndoe@example.com",
          "primary": true
        }
      ],
      "meta": {
        "created": "2019-05-29T12:45:30.671Z",
        "lastModified": "2019-05-29T12:45:30.671Z",
        "resourceType": "User"
      },
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "name": {
        "givenName": "John",
        "familyName": "Doe",
        "formatted": "John Doe"
      },
      "id": "66ad3522-2251-4531-abff-3e3aad66b650"
    }

Update a Cloud Directory user

Updates an existing Cloud Directory user. Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.set.cd.user

Auditing

Calling this method generates the following auditing event.

  • appid.cloud-directory-user.update

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

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.

Example responses
  • {
      "displayName": "John Doe",
      "active": true,
      "emails": [
        {
          "value": "johndoe@example.com",
          "primary": true
        }
      ],
      "meta": {
        "created": "2019-05-29T12:45:30.671Z",
        "lastModified": "2019-05-29T12:45:30.671Z",
        "resourceType": "User"
      },
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "name": {
        "givenName": "John",
        "familyName": "Doe",
        "formatted": "John Doe"
      },
      "id": "66ad3522-2251-4531-abff-3e3aad66b650"
    }

Delete a Cloud Directory user

Deletes an existing Cloud Directory record (without removing the associated profile). Learn more.

To remove a Cloud Directory user, use the Delete Cloud Delete user and profile API.

Note: This action cannot be undone.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.delete.cd.user

Auditing

Calling this method generates the following auditing event.

  • appid.cloud-directory-user.delete

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.

Invalidate all SSO sessions

Invalidate all the user's SSO sessions.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.post.sso.logout

Auditing

Calling this method generates the following auditing event.

  • appid.cloud-directory-user-sso.set-off

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

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

  • No content. All SSO sessions of the user were invalidated.

  • The tenantId is invalid.

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

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

  • The Cloud Directory user 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. Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.export.cd.users

Auditing

Calling this method generates the following auditing event.

  • appid.cloud-directory-users.get

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.

    Possible values: 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.

Example responses
  • {
      "itemsPerPage": 2,
      "totalResults": 2,
      "users": [
        {
          "scimUser": {
            "originalId": "e403878c-3ab5-4e99-8953-bb57b05387d8",
            "name": {
              "givenName": "Jane",
              "familyName": "Doe",
              "formatted": "Jane Doe"
            },
            "displayName": "Jane Doe",
            "active": true,
            "emails": [
              {
                "value": "user09857654@mail.com",
                "primary": true
              }
            ]
          },
          "passwordHash": "xveImwVxuO7jxRQlRveKgBXD4WoAG0aIHVTY0GLSuTQbfTIsTNy753LFE9kdReAnBTIbSOeQ69UKJdnIxBZZkm9oWf8wsmwWeZwU9njZDDdhxzJWfvAv6Y/XjAqvNdWvJfV3Tag/zwQtKaET6Sc2gSbFL8L1X1wRR/msNA+NSfg=",
          "passwordHashAlg": "PBKDF2WithHmacSHA512",
          "profile": {
            "attributes": {
              "points": 100
            }
          },
          "roles": []
        },
        {
          "scimUser": {
            "originalId": "66ad3522-2251-4531-abff-3e3aad66b650",
            "userName": "myUserName",
            "name": {
              "givenName": "John",
              "familyName": "Doe",
              "formatted": "John Doe"
            },
            "displayName": "John Doe",
            "active": true,
            "emails": [
              {
                "value": "user0987654@mail.com",
                "primary": true
              }
            ]
          },
          "passwordHash": "YKmBYObTprREAKqjl8F94ofE5lF5lr7Zuc/eJ0Sylvx6IOgI97M56n16U0aGWqBVTu2/P8xayrr6utoH/Uok5v/3Ct9jddXlxhkA1odqgQslJdXiCcBHn/49xU9iejCu6p3PL/81vBfcBGxTll2xeHzF+0qF4rxzn91H6TuNH4o=",
          "passwordHashAlg": "PBKDF2WithHmacSHA512",
          "profile": {
            "attributes": {
              "points": 150
            }
          },
          "roles": [
            "adult",
            "child"
          ]
        }
      ]
    }

Import Cloud Directory users

Imports Cloud Directory users list that was exported using the /export API. Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.import.cd.users

Auditing

Calling this method generates the following auditing event.

  • appid.cloud-directory-users.import

Request

Custom Headers

  • Allowable values: [application/json,application/x-www-form-urlencoded,multipart/form-data]

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

Examples:
View

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.

Example responses
  • {
      "added": 30,
      "failed": 1,
      "failReasons": [
        {
          "originalId": "773f85b4-72f4-480d-aca8-755f517c4508",
          "id": "664f85b4-72f4-480d-aca8-755f517c4909",
          "email": "user@mail.com",
          "userName": "myUserName",
          "error": {
            "message": "The email that you entered is already taken.",
            "status": 409
          }
        }
      ]
    }

Get Cloud Directory SCIM and attributes

Returns the Cloud Directory user SCIM and the profile related to it. Learn more.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.get.cd.userinfo

Auditing

Calling this method generates the following auditing event.

  • appid.cloud-directory-userinfo.read

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

  • Returns the user's data.

  • Invalid tenantId/userId.

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

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

  • The user is not found.

Example responses
  • {
      "sub": "122e1dd7-2a7f-18fb-b8ed-ed78c3f92c2b",
      "identities": [
        {
          "provider": "cloud_directory",
          "id": "773f85b4-72f4-480d-aca8-755f517c4508",
          "idpUserInfo": {
            "displayName": "John Doe",
            "active": true,
            "emails": [
              {
                "value": "johndoe@example.com",
                "primary": true
              }
            ],
            "meta": {
              "created": "2019-05-29T12:45:30.671Z",
              "lastModified": "2019-05-29T12:45:30.671Z",
              "resourceType": "User"
            },
            "schemas": [
              "urn:ietf:params:scim:schemas:core:2.0:User"
            ],
            "name": {
              "givenName": "John",
              "familyName": "Doe",
              "formatted": "John Doe"
            },
            "id": "66ad3522-2251-4531-abff-3e3aad66b650"
          }
        }
      ],
      "attributes": {
        "points": 150
      }
    }

Delete an TOTP registration

Deletes a user TOTP registration. If a user never used TOTP , this operation will have no effect.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • appid.mgmt.del.totp.channel

Auditing

Calling this method generates the following auditing event.

  • appid.cloud-directory-user.delete

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 OTP registration 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.