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 | 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. |
Related APIs
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
Response
config
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.
{ "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
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.
Example:
true
Example:
appID
Example:
appsecret
config
Response
config
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.
{ "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
Response
config
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.
{ "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
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.
Example:
true
Example:
appID
Example:
appsecret
config
Response
config
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.
{ "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
Response
Example:
true
Example:
appID
Example:
appsecret
Example:
true
Example:
true
config
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
Update IBMid IDP configuration
Configure IBMid to set up a single sign-on experience for your users.
PUT /management/v4/{tenantId}/config/idps/ibmid
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.
Example:
true
Example:
appID
Example:
appsecret
Example:
true
Example:
true
config
Response
config
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.
{ "isActive": true, "config": { "idpId": "client_id", "secret": "client_secret", "preProd": false, "ciBased": true }, "redirectURL": "https://example.com" }
Response
config
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.
{ "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
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.
config
Response
config
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.
{ "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
Response
Example:
true
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.
{ "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
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.
Example:
true
Example:
true
Allowable values: [
FULL
,RESTRICTIVE
,OFF
]Allowable values: [
email
]
identityConfirmation
Example:
true
interactions
Example:
true
Allowable values: [
email
,userName
]
config
Response
Example:
true
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.
{ "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
Response
- Examples:View
config
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.
{ "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
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.
Example:
true
- Examples:View
Allowable values: [
urn:oasis:names:tc:SAML:2.0:ac:classes:InternetProtocol
,urn:oasis:names:tc:SAML:2.0:ac:classes:InternetProtocolPassword
,urn:oasis:names:tc:SAML:2.0:ac:classes:Kerberos
,urn:oasis:names:tc:SAML:2.0:ac:classes:MobileOneFactorUnregistered
,urn:oasis:names:tc:SAML:2.0:ac:classes:MobileTwoFactorUnregistered
,urn:oasis:names:tc:SAML:2.0:ac:classes:MobileOneFactorContract
,urn:oasis:names:tc:SAML:2.0:ac:classes:MobileTwoFactorContract
,urn:oasis:names:tc:SAML:2.0:ac:classes:Password
,urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
,urn:oasis:names:tc:SAML:2.0:ac:classes:PreviousSession
,urn:oasis:names:tc:SAML:2.0:ac:classes:X509
,urn:oasis:names:tc:SAML:2.0:ac:classes:PGP
,urn:oasis:names:tc:SAML:2.0:ac:classes:SPKI
,urn:oasis:names:tc:SAML:2.0:ac:classes:XMLDSig
,urn:oasis:names:tc:SAML:2.0:ac:classes:Smartcard
,urn:oasis:names:tc:SAML:2.0:ac:classes:SmartcardPKI
,urn:oasis:names:tc:SAML:2.0:ac:classes:SoftwarePKI
,urn:oasis:names:tc:SAML:2.0:ac:classes:Telephony
,urn:oasis:names:tc:SAML:2.0:ac:classes:NomadTelephony
,urn:oasis:names:tc:SAML:2.0:ac:classes:PersonalTelephony
,urn:oasis:names:tc:SAML:2.0:ac:classes:AuthenticatedTelephony
,urn:oasis:names:tc:SAML:2.0:ac:classes:SecureRemotePassword
,urn:oasis:names:tc:SAML:2.0:ac:classes:TLSClient
,urn:oasis:names:tc:SAML:2.0:ac:classes:TimeSyncToken
,urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified
]Allowable values: [
exact
,maximum
,minimum
,better
]
authnContext
config
Response
- Examples:View
config
certificates
validation_data
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.
{ "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
Response
- Examples:View
- Examples:View
- Examples:View
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.
{ "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
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
- Examples:View
- Examples:View
Response
- Examples:View
- Examples:View
- Examples:View
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.
{ "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
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.
{ "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
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
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
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.
{ "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
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.
Example:
true
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
Get widget texts
Get the theme texts of the App ID login widget. Learn more.
GET /management/v4/{tenantId}/config/ui/theme_text
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.
{ "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
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.
Possible values: length ≤ 100
Example:
Login
Possible values: length ≤ 3000
Example:
Powered by App ID
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
Get widget colors
Get the colors of the App ID login widget. Learn more.
GET /management/v4/{tenantId}/config/ui/theme_color
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.
{ "headerColor": "#EEF2F5" }
Update widget colors
Update the colors of the App ID login widget. Learn more.
PUT /management/v4/{tenantId}/config/ui/theme_color
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.
Example:
#EEF2F5
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
Delete widget logo
You can delete the image file shown in the login widget. Learn more.
DELETE /management/v4/{tenantId}/config/ui/media
Get widget logo
Returns the link to the custom logo image of the login widget. Learn more.
GET /management/v4/{tenantId}/config/ui/media
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.
{ "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
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
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
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.
<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}
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.
{ "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}
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.
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.
{ "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}
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
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
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.
{ "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
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
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
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
Response
from
reply_to
Possible values: 900 ≤ value ≤ 604800
senderDetails
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.
{ "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
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.
from
reply_to
Possible values: 900 ≤ value ≤ 604800
senderDetails