App ID Management | IBM Cloud API Docs

Introduction

Last updated: 2021-10-15

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.

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

tenantId
Required*
string
The service tenantId. The tenantId can be found in the service credentials.

Response

Response Body

facebookConfigParams

Status Code

200
Returns a JSON object of the Facebook identity provider configuration, including the status and credentials. Learn more.
400
The tenantId or request body is missing or invalid.
401
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
403
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
500
Returned in case of internal server error.

Example responses

Status 200

{
  "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"
}

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

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

Path Parameters

tenantId
Required*
string
The service tenantId. The tenantId can be found in the service credentials.

Request Body

Required*

facebookGoogleConfigParams

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

Response

Response Body

facebookConfigParamsPUT

Status Code

200
The Facebook configuration was updated. Returns a JSON object of the idp data.
400
The tenantId or request body is missing or invalid.
401
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
403
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
500
Returned in case of internal server error.

Example responses

Status 200

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

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

tenantId
Required*
string
The service tenantId. The tenantId can be found in the service credentials.

Response

Response Body

googleConfigParams

Status Code

200
Returns a JSON object of the Google identity provider configuration, including the status and credentials. Learn more.
400
The tenantId or request body is missing or invalid.
401
The user is unauthorized. To be authorized a user needs an IAM token with the valid permissions.
403
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
500
Returned in case of internal server error.

Example responses

Status 200

{
  "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"
}

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

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

Path Parameters

tenantId
Required*
string
The service tenantId. The tenantId can be found in the service credentials.

Request Body

Required*

facebookGoogleConfigParams

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

Response

Response Body

googleConfigParamsPUT

Status Code

200
The Google configuration was updated. Returns a JSON object of the idp data.
400
The tenantId or request body is missing or invalid. The tenantId can be found in the service credentials.
401
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
403
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
500
Returned in case of internal server error.

Example responses

Status 200

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

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

tenantId
Required*
string
The service tenantId. The tenantId can be found in the service credentials.

Response

Response Body

ibmidConfigParams

Status Code

200
Returns a JSON object of the IBMid identity provider configuration, including the status and credentials.
400
The tenantId or request body is missing or invalid.
401
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
403
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
500
Returned in case of internal server error.

No Sample Response

This method does not specify any sample responses.

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

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

Path Parameters

tenantId
Required*
string
The service tenantId. The tenantId can be found in the service credentials.

Request Body

Required*

ibmidConfigParams

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

Response

Response Body

ibmidConfigParamsPUT

Status Code

200
The IBMid configuration was updated. Returns a JSON object of the idp data.
400
The tenantId or request body is missing or invalid.
401
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
403
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
500
Returned in case of internal server error.

Example responses

Status 200

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

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

tenantId
Required*
string
The service tenantId. The tenantId can be found in the service credentials.

Response

Response Body

customIdPConfigParams

Status Code

200
Returns a JSON object of the Custom identity configuration containing the PEM public key and the isActive status.
400
The tenantId or request body is missing or invalid.
401
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
403
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
500
Returned in case of internal server error.

Example responses

Status 200

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

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

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

Path Parameters

tenantId
Required*
string
The service tenantId. The tenantId can be found in the service credentials.

Request Body

Required*

customIdPConfigParams

The identity provider configuration as a JSON object.

Examples:

View

Response

Response Body

customIdPConfigParams

Status Code

200
The Custom identity configuration was updated. Returns a JSON object of the updated configuration.
400
The tenantId or request body is missing or invalid.
401
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
403
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
500
Returned in case of internal server error.

Example responses

Status 200

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

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

tenantId
Required*
string
The service tenantId. The tenantId can be found in the service credentials.

Response

Response Body

cloudDirectoryResponse

Status Code

200
Returns a JSON object of the Cloud Directory identity provider configuration, including the status and credentials.
400
The tenantId or request body is missing or invalid.
401
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
403
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
500
Returned in case of internal server error.

Example responses

Status 200

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

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

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

Path Parameters

tenantId
Required*
string
The service tenantId. The tenantId can be found in the service credentials.

Request Body

Required*

object

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

Response

Response Body

cloudDirectoryResponse

Status Code

200
The Cloud Directory configuration was updated. Returns a JSON object of the idp data.
400
The tenantId or request body is missing or invalid.
401
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
403
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
500
Returned in case of internal server error.

Example responses

Status 200

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

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

tenantId
Required*
string
The service tenantId. The tenantId can be found in the service credentials.

Response

Response Body

samlResponse

Status Code

200
Returns the identity provider configuration for SAML as a JSON object.
400
The tenantId or request body is missing or invalid. The tenantId can be found in the service credentials.
401
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
403
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
500
Returned in case of internal server error.

Example responses

Status 200

{
  "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
  }
}

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

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

Path Parameters

tenantId
Required*
string
The service tenantId. The tenantId can be found in the service credentials.

Request Body

Required*

object

The identity provider configuration as a JSON object.

Response

Response Body

samlResponseWithValidationData

Status Code

200
The SAML configuration was updated. Returns a JSON object of the idp data.
400
The tenantId or request body is missing or invalid.
401
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
403
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.
500
Returned in case of internal server error.

Example responses

Status 200

{
  "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."
      }
    ]
  }
}

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

tenantId
Required*
string
The service tenantId. The tenantId can be found in the service credentials.

Response

Response Body

tokensConfigResponse

Status Code

200
Returns a JSON object of the App ID tokens properties.
400
The tenantId or request body is missing or invalid.
401
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
403
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

Example responses

Status 200

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

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

Path Parameters

tenantId
Required*
string
The service tenantId. The tenantId can be found in the service credentials.

Request Body

Required*

tokensConfigResponse

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

Examples:

View

Response

Response Body

tokensConfigResponse

Status Code

200
The token configuration was updated.
400
The tenantId or request body is missing or invalid.
401
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
403
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

Example responses

Status 200

{
  "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
  }
}

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

tenantId
Required*
string
The service tenantId. The tenantId can be found in the service credentials.

Response

Response Body

redirectUriResponse

Status Code

200
An array of the redirect URIs is returned as a JSON object.
400
The tenantId parameter is missing or invalid.
401
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
403
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

Example responses

Status 200

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

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

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

Path Parameters

tenantId
Required*
string
The service tenantId. The tenantId can be found in the service credentials.

Request Body

Required*

redirectUriConfig

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

Response

Status Code

204
No content. The redirect URIs were updated.
400
The tenantId or request body is missing or invalid.
401
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
403
The user has insufficient permissions. Contact the service owner or admin to verify permissions.

No Sample Response

This method does not specify any sample responses.

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

tenantId
Required*
string
The service tenantId. The tenantId can be found in the service credentials.

Response

Response Body

object

Status Code

200
The current profiles status is returned as a JSON object.
400
The tenantId is missing or invalid.
401
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
403
The user has insufficient permissions. Contact the service owner or admin to verify permissions.

Example responses

{ "isActive": false }

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

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

Path Parameters

tenantId
Required*
string
The service tenantId. The tenantId can be found in the service credentials.

Request Body

Required*

profiles

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

Response

Status Code

204
No content. The user profiles status was updated.
400
The tenantId or request body is missing or invalid.
401
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
403
The 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 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

tenantId
Required*
string
The service tenantId. The tenantId can be found in the service credentials.

Response

Response Body

object

Status Code

200
The current color configuration is returned as a JSON object.
400
The tenantId is missing or invalid.
401
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
403
The user has insufficient permissions. Contact the service owner or admin to verify permissions.

Example responses

Status 200

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

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

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

Path Parameters

tenantId
Required*
string
The service tenantId. The tenantId can be found in the service credentials.

Request Body

Required*

themeTextConfigParam

The texts of the widget.

Response

Status Code

204
No content, the service login widget header color was updated.
400
The tenantId or request body is missing or invalid.
401
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
403
The user has insufficient permissions. Contact the service owner or admin to verify permissions.

No Sample Response

This method does not specify any sample responses.

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

tenantId
Required*
string
The service tenantId. The tenantId can be found in the service credentials.

Response

Response Body

object

Status Code

200
The current color configuration is returned as a JSON object.
400
The tenantId is missing or invalid.
401
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
403
The user has insufficient permissions. Contact the service owner or admin to verify permissions.

Example responses

{ "headerColor": "#EEF2F5" }

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

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

Path Parameters

tenantId
Required*
string
The service tenantId. The tenantId can be found in the service credentials.

Request Body

Required*

themeColorConfigParam

The colors of the widget.

Response

Status Code

204
No content, the service login widget header color was updated.
400
The tenantId or request body is missing or invalid.
401
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
403
The user has insufficient permissions. Contact the service owner or admin to verify permissions.

No Sample Response

This method does not specify any sample responses.

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

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

Request

Path Parameters

tenantId
Required*
string
The service tenantId. The tenantId can be found in the service credentials.

Query Parameters

mediaType
Required*
string
The type of media. You can upload JPG or PNG files.

Allowable values: [logo]

Response

Status Code

204
The logo was deleted.
400
The tenantId or file type are missing.
401
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
403
The user has insufficient permissions. Contact the service owner or admin to verify permissions.

No Sample Response

This method does not specify any sample responses.

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

tenantId
Required*
string
The service tenantId. The tenantId can be found in the service credentials.

Response

Response Body

object

Status Code

200
A JSON object with the current media configurations.
400
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.
401
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
403
The user has insufficient permissions. Contact the service owner or admin to verify permissions.

Example responses

{ "image": "image-url" }

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

tenantId
Required*
string
The service tenantId. The tenantId can be found in the service credentials.

Query Parameters

mediaType
Required*
string
The type of media. You can upload JPG or PNG files.

Allowable values: [logo]

Form Parameters

file
Required*
binary
The image file. The recommended size is 320x320 px. The maxmimum files size is 100kb.

Response

Status Code

204
No content. The service login widget logo was updated.
400
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.
401
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
403
The user has insufficient permissions. Contact the service owner or admin to verify permissions.

No Sample Response

This method does not specify any sample responses.

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

tenantId
Required*
string
The service tenantId. The tenantId can be found in the service credentials.

Response

Response Body

string

Status Code

200
An xml snippet that contains the metadata for using SAML as a service provider.
400
The tenantId parameter is missing or invalid.
500
Returned in case of internal server error.

Example responses

Status 200

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

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

tenantId
Required*
string
The service tenantId. The tenantId can be found in the service credentials.
templateName
Required*
string
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]
language
Required*
string
Preferred language for resource. Format as described at RFC5646. According to the configured languages codes returned from the GET /management/v4/{tenantId}/config/ui/languages API.

Response

Response Body

getTemplate

Status Code

200
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.
400
The tenantId or templateName are missing or invalid or language is not in the app localization configuration.
401
The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.
403
The user has insufficient permissions. Contact the service owner or admin to verify permissions.

Example responses

Status 200

{
  "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="
}

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

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

Path Parameters

tenantId
Required*
string
The service tenantId. The tenantId can be found in the service credentials.
templateName
Required*
string
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]
language
Required*
string
Preferred language for resource. Format as described at RFC5646. According to the configured languages codes returned from the GET /management/v4/{tenantId}/config/ui/languages API.

Request Body

Required*

setTemplate

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

Response Body

getTemplate

Status Code

200
The email template properties is returned as a JSON object.
201
The created email template properties are returned as a JSON object.
204
No content. The template configuration was updated.(in case request Prefer header is return_minimal)
400
The tenantId or request body is missing or invalid.
401
The user is unauthorized.
403
The user has insufficient permissions.

Example responses

Status 200

{
  "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="
}

Status 201

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

tenantId
Required*
string
The service tenantId. The tenantId can be found in the service credentials.
templateName
Required*
string
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]
language
Required*
string
Preferred language for resource. Format as described at RFC5646. According to the configured languages codes returned from the GET /management/v4/{tenantId}/config/ui/languages API.

Response

Status Code

204
The template was deleted.
400
The tenantId is missing or invalid.
401
The user is unauthorized. To be authorized, a user needs an IAM token with the valid permissions.
403
The user has insufficient permissions. Contact a service owner or admin to verify permissions.
404
The template does not exist.

No Sample Response

This method does not specify any sample responses.

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

tenantId
Required*
string
The service tenantId. The tenantId can be found in the service credentials.

Response

Response Body

getLanguages

Status Code

200
The localization data is returned as a JSON object.
400
The tenantId or languages are missing or invalid.
401
The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.
403
The user has insufficient permissions. Contact the service owner or admin to verify permissions.

Example responses

Status 200

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

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

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

Path Parameters

tenantId
Required*
string
The service tenantId. The tenantId can be found in the service credentials.

Request Body

getLanguages

User localization configuration. Available languages codes

Examples:

View

Response

Status Code

204
'No content. The localization configuration was updated.'
400
The tenantId or request body is missing or invalid.
401
The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.
403
The user has insufficient permissions. Contact the service owner or admin to verify permissions.

No Sample Response

This method does not specify any sample responses.

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

tenantId
Required*
string
The service tenantId. The tenantId can be found in the service credentials.

Response

Response Body

cloudDirectorySenderDetails

Status Code

200
The sender details configuration for a Cloud Directory email returned as a JSON object.
400
The tenantId parameter is missing or invalid or invalid request.
401
The user is unauthorized. To be authorized, a user needs an IAM token with valid permissions.
403
The user has insufficient permissions. Contact the service owner or admin to verify user permissions.

Example responses

Status 200

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

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

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

Path Parameters

tenantId
Required*
string
The service tenantId. The tenantId can be found in the service credentials.

Request Body

Required*

cloudDirectorySenderDetails

A JSON object that contains the sender details.

Examples:

View

Introduction

Endpoint URLs

Authentication

Auditing

Error handling

Related APIs

Methods

Get Facebook IDP configuration

Authorization

Auditing

Request

Path Parameters

tenantId

Response

Response Body

isActive

config

idpId

secret

Status Code

200

400

401

403

500

Update Facebook IDP configuration

Authorization

Auditing

Request

Custom Headers

Content-Type

Path Parameters

tenantId

Request Body

isActive

config

idpId

secret

other property

Response

Response Body

isActive

config

idpId

secret

Status Code

200

400

401

403

500

Get Google IDP configuration

Authorization

Auditing

Request

Path Parameters

tenantId

Response

Response Body

isActive

config

idpId

secret

Status Code

200

400

401

403

500

Update Google IDP configuration

Authorization

Auditing

Request

Custom Headers

Content-Type

Path Parameters

tenantId

Request Body

isActive

config