Get account configurations

GET /v1/accounts/{account_id}/settings/identity

Returns the details of an account's configuration.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.account.get

Request

Path Parameters

account_id

Required *

string

Unique ID of the account.

Query Parameters

include_history

boolean

Defines if the entity history is included in the response.

resolve_user_mfa

boolean

Enrich MFA exemptions with user PI.

Response

200 - Successful response. No further actions.

context

ResponseContext

Context with key properties for problem determination.

account_id

string

Unique ID of the account.

entity_tag

string

Version of the account settings.

history

array

History of the Account Settings.

restrict_create_service_id

string

Defines whether or not creating the resource is access controlled. Valid values: * RESTRICTED - only users assigned the 'Service ID creator' role on the IAM Identity Service can create service IDs, including the account owner * NOT_RESTRICTED - all members of an account can create service IDs * NOT_SET - to 'unset' a previous set value

restrict_create_platform_apikey

string

Defines whether or not creating the resource is access controlled. Valid values: * RESTRICTED - only users assigned the 'Service ID creator' role on the IAM Identity Service can create service IDs, including the account owner * NOT_RESTRICTED - all members of an account can create service IDs * NOT_SET - to 'unset' a previous set value

allowed_ip_addresses

string

Defines the IP addresses and subnets from which IAM tokens can be created for the account.

mfa

string

MFA trait definitions as follows: * NONE - No MFA trait set * NONE_NO_ROPC- No MFA, disable CLI logins with only a password * TOTP - For all non-federated IBMId users * TOTP4ALL - For all users * LEVEL1 - Email-based MFA for all users * LEVEL2 - TOTP-based MFA for all users * LEVEL3 - Security Key MFA for all users

session_expiration_in_seconds

string

Defines the session expiration in seconds for the account. Valid values: * Any whole number between between '900' and '86400' * NOT_SET - To unset account setting and use service default

session_invalidation_in_seconds

string

Defines the period of time in seconds in which a session will be invalidated due to inactivity. Valid values: * Any whole number between '900' and '7200' * NOT_SET - To unset account setting and use service default

max_sessions_per_identity

string

Defines the max allowed sessions per identity required by the account. Valid values: * Any whole number greater than 0 * NOT_SET - To unset account setting and use service default

system_access_token_expiration_in_seconds

string

Defines the access token expiration in seconds. Valid values: * Any whole number between '900' and '3600' * NOT_SET - To unset account setting and use service default

system_refresh_token_expiration_in_seconds

string

Defines the refresh token expiration in seconds. Valid values: * Any whole number between '900' and '259200' * NOT_SET - To unset account setting and use service default

restrict_user_list_visibility

string

Defines whether or not user visibility is access controlled. Valid values: * RESTRICTED - users can view only specific types of users in the account, such as those the user has invited to the account, or descendants of those users based on the classic infrastructure hierarchy * NOT_RESTRICTED - any user in the account can view other users from the Users page in IBM Cloud console

user_mfa

array

List of users that are exempted from the MFA requirement of the account.

restrict_user_domains

array

Defines if account invitations are restricted to specified domains. To remove an entry for a realm_id, perform an update (PUT) request with only the realm_id set.

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

500 - Internal Server error. Response if unexpected error situation happened.

Update account configurations

PUT /v1/accounts/{account_id}/settings/identity

Allows a user to configure settings on their account with regards to MFA, MFA excemption list, session lifetimes, access control for creating new identities, and enforcing IP restrictions on token creation.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.account.update

Auditing

Calling this method generates the following auditing event.

• iam-identity.accountsettings.update

Request

Request Body

AccountSettingsRequest

Request to update an account's settings.

restrict_create_service_id

string

Defines whether or not creating the resource is access controlled. Valid values: * RESTRICTED - only users assigned the 'Service ID creator' role on the IAM Identity Service can create service IDs, including the account owner * NOT_RESTRICTED - all members of an account can create service IDs * NOT_SET - to 'unset' a previous set value

restrict_create_platform_apikey

string

Defines whether or not creating the resource is access controlled. Valid values: * RESTRICTED - only users assigned the 'Service ID creator' role on the IAM Identity Service can create service IDs, including the account owner * NOT_RESTRICTED - all members of an account can create service IDs * NOT_SET - to 'unset' a previous set value

allowed_ip_addresses

string

Defines the IP addresses and subnets from which IAM tokens can be created for the account.

mfa

string

MFA trait definitions as follows: * NONE - No MFA trait set * NONE_NO_ROPC- No MFA, disable CLI logins with only a password * TOTP - For all non-federated IBMId users * TOTP4ALL - For all users * LEVEL1 - Email-based MFA for all users * LEVEL2 - TOTP-based MFA for all users * LEVEL3 - Security Key MFA for all users

user_mfa

array

List of users that are exempted from the MFA requirement of the account.

session_expiration_in_seconds

string

Defines the session expiration in seconds for the account. Valid values: * Any whole number between between '900' and '86400' * NOT_SET - To unset account setting and use service default

session_invalidation_in_seconds

string

Defines the period of time in seconds in which a session will be invalidated due to inactivity. Valid values: * Any whole number between '900' and '7200' * NOT_SET - To unset account setting and use service default

max_sessions_per_identity

string

Defines the max allowed sessions per identity required by the account. Valid values: * Any whole number greater than 0 * NOT_SET - To unset account setting and use service default

system_access_token_expiration_in_seconds

string

Defines the access token expiration in seconds. Valid values: * Any whole number between '900' and '3600' * NOT_SET - To unset account setting and use service default

system_refresh_token_expiration_in_seconds

string

Defines the refresh token expiration in seconds. Valid values: * Any whole number between '900' and '259200' * NOT_SET - To unset account setting and use service default

restrict_user_list_visibility

string

Defines whether or not user visibility is access controlled. Valid values: * RESTRICTED - users can view only specific types of users in the account, such as those the user has invited to the account, or descendants of those users based on the classic infrastructure hierarchy * NOT_RESTRICTED - any user in the account can view other users from the Users page in IBM Cloud console

restrict_user_domains

array

Defines if account invitations are restricted to specified domains. To remove an entry for a realm_id, perform an update (PUT) request with only the realm_id set.

Path Parameters

account_id

Required *

string

The id of the account to update the settings for.

Query Parameters

Response

200 - Successful account configuration update.

context

ResponseContext

Context with key properties for problem determination.

account_id

string

Unique ID of the account.

entity_tag

string

Version of the account settings.

history

array

History of the Account Settings.

restrict_create_service_id

string

Defines whether or not creating the resource is access controlled. Valid values: * RESTRICTED - only users assigned the 'Service ID creator' role on the IAM Identity Service can create service IDs, including the account owner * NOT_RESTRICTED - all members of an account can create service IDs * NOT_SET - to 'unset' a previous set value

restrict_create_platform_apikey

string

Defines whether or not creating the resource is access controlled. Valid values: * RESTRICTED - only users assigned the 'Service ID creator' role on the IAM Identity Service can create service IDs, including the account owner * NOT_RESTRICTED - all members of an account can create service IDs * NOT_SET - to 'unset' a previous set value

allowed_ip_addresses

string

Defines the IP addresses and subnets from which IAM tokens can be created for the account.

mfa

string

MFA trait definitions as follows: * NONE - No MFA trait set * NONE_NO_ROPC- No MFA, disable CLI logins with only a password * TOTP - For all non-federated IBMId users * TOTP4ALL - For all users * LEVEL1 - Email-based MFA for all users * LEVEL2 - TOTP-based MFA for all users * LEVEL3 - Security Key MFA for all users

session_expiration_in_seconds

string

Defines the session expiration in seconds for the account. Valid values: * Any whole number between between '900' and '86400' * NOT_SET - To unset account setting and use service default

session_invalidation_in_seconds

string

Defines the period of time in seconds in which a session will be invalidated due to inactivity. Valid values: * Any whole number between '900' and '7200' * NOT_SET - To unset account setting and use service default

max_sessions_per_identity

string

Defines the max allowed sessions per identity required by the account. Valid values: * Any whole number greater than 0 * NOT_SET - To unset account setting and use service default

system_access_token_expiration_in_seconds

string

Defines the access token expiration in seconds. Valid values: * Any whole number between '900' and '3600' * NOT_SET - To unset account setting and use service default

system_refresh_token_expiration_in_seconds

string

Defines the refresh token expiration in seconds. Valid values: * Any whole number between '900' and '259200' * NOT_SET - To unset account setting and use service default

restrict_user_list_visibility

string

Defines whether or not user visibility is access controlled. Valid values: * RESTRICTED - users can view only specific types of users in the account, such as those the user has invited to the account, or descendants of those users based on the classic infrastructure hierarchy * NOT_RESTRICTED - any user in the account can view other users from the Users page in IBM Cloud console

user_mfa

array

List of users that are exempted from the MFA requirement of the account.

restrict_user_domains

array

Defines if account invitations are restricted to specified domains. To remove an entry for a realm_id, perform an update (PUT) request with only the realm_id set.

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

500 - Internal Server error.

Get effective account settings configuration

GET /v1/accounts/{account_id}/effective_settings/identity

Returns effective account settings for given account ID

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.account.getEffectiveAccountSettings

Request

Path Parameters

account_id

Required *

string

Unique ID of the account.

Query Parameters

include_history

boolean

Defines if the entity history is included in the response.

resolve_user_mfa

boolean

Enrich MFA exemptions with user information.

Response

200 - Successful response. No further actions.

context

ResponseContext

Context with key properties for problem determination.

account_id

string

Unique ID of the account.

effective

AccountSettingsEffectiveSection

effective section.

account

AccountSettingsResponse

account section.

assigned_templates

array

assigned template section.

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

500 - Internal Server error. Response if unexpected error situation happened.

Get API keys for a given service or user IAM ID and account ID

GET /v1/apikeys

Returns the list of API key details for a given service or user IAM ID and account ID. Users can manage user API keys for themself, or service ID API keys for service IDs they have access to.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.apikey.list
• iam-identity.apikey.manage (if scope='account')

Request

Path Parameters

Query Parameters

account_id

string

Account ID of the API keys to query. If a service IAM ID is specified in iam_id then account_id must match the account of the IAM ID. If a user IAM ID is specified in iam_id then then account_id must match the account of the Authorization token.

iam_id

string

IAM ID of the API keys to be queried. The IAM ID may be that of a user or a service. For a user IAM ID iam_id must match the Authorization token.

pagesize

integer

Optional size of a single page. Default is 20 items per page. Valid range is 1 to 100.

pagetoken

string

Optional Prev or Next page token returned from a previous query execution. Default is start with first page.

scope

string

Optional parameter to define the scope of the queried API keys. Can be 'entity' (default) or 'account'.

type

string

Optional parameter to filter the type of the queried API keys. Can be 'user' or 'serviceid'.

sort

string

Optional sort property, valid values are name, description, created_at and created_by. If specified, the items are sorted by the value of this property.

order

string

Optional sort order, valid values are asc and desc. Default: asc.

include_history

boolean

Defines if the entity history is included in the response.

filter

string

An optional filter query parameter used to refine the results of the search operation. For more information see Filtering list results section.

group_id

string

Optional group ID of the service ID(s) to which the searched API keys are bound. If this parameter is not provided the default group is applied on service ID API keys. For user API keys this parameter is ignored as they always belong to the default group.

Response

200 - Successful operation.

context

ResponseContext

Context with key properties for problem determination.

offset

integer

The offset of the current page.

limit

integer

Optional size of a single page. Default is 20 items per page. Valid range is 1 to 100

first

string

Link to the first page.

previous

string

Link to the previous available page. If 'previous' property is not part of the response no previous page is available.

next

string

Link to the next available page. If 'next' property is not part of the response no next page is available.

apikeys

array

List of API keys based on the query paramters and the page size. The apikeys array is always part of the response but might be empty depending on the query parameters values provided.

400 - Parameter validation failed.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

401 - The incoming request did not contain a valid authentication information.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

404 - User iam_id or account_id does not match Authorization token, service ID of the IAM ID not found.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

500 - Internal Server error.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

POST /v1/apikeys

Creates an API key for a UserID or service ID. Users can manage user API keys for themself, or service ID API keys for service IDs they have access to.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.apikey.create

Auditing

Calling this method generates the following auditing event.

• iam-identity.user-apikey.create
• iam-identity.serviceid-apikey.create

Request

Request Body

CreateApiKeyRequest

Request to create an API key.

name

Required *

string

Name of the API key. The name is not checked for uniqueness. Therefore multiple names with the same value can exist. Access is done via the UUID of the API key.

description

string

The optional description of the API key. The 'description' property is only available if a description was provided during a create of an API key.

iam_id

Required *

string

The iam_id that this API key authenticates.

account_id

string

The account ID of the API key.

apikey

string

You can optionally passthrough the API key value for this API key. If passed, a minimum length validation of 32 characters for that apiKey value is done, i.e. the value can contain any characters and can even be non-URL safe, but the minimum length requirement must be met. If omitted, the API key management will create an URL safe opaque API key value. The value of the API key is checked for uniqueness. Ensure enough variations when passing in this value.

store_value

boolean

Send true or false to set whether the API key value is retrievable in the future by using the Get details of an API key request. If you create an API key for a user, you must specify `false` or omit the value. We don't allow storing of API keys for users.

support_sessions

boolean

Defines whether you can manage CLI login sessions for the API key. When `true`, sessions are created and can be reviewed or revoked. When `false`, no sessions are tracked. To block access, delete or rotate the API key. Available only for user API keys.

action_when_leaked

string

Defines the action to take when API key is leaked, valid values are 'none', 'disable' and 'delete'.

expires_at

string

Date and time when the API key becomes invalid, ISO 8601 datetime in the format 'yyyy-MM-ddTHH:mm+0000'. WARNING An API key will be permanently and irrevocably deleted when both the expires_at and modified_at timestamps are more than ninety (90) days in the past, regardless of the key’s locked status or any other state.

Path Parameters

Query Parameters

Response

201 - API key successfully created. Response if the Object could be created in the persistence layer.

context

ResponseContext

Context with key properties for problem determination.

id

string

Unique identifier of this API Key.

entity_tag

string

Version of the API Key details object. You need to specify this value when updating the API key to avoid stale updates.

crn

string

Cloud Resource Name of the item. Example Cloud Resource Name: 'crn:v1:bluemix:public:iam-identity:us-south:a/myaccount::apikey:1234-9012-5678'

locked

boolean

The API key cannot be changed if set to true.

disabled

boolean

Defines if API key is disabled, API key cannot be used if 'disabled' is set to true.

created_at

string

If set contains a date time string of the creation date in ISO format.

created_by

string

IAM ID of the user or service which created the API key.

modified_at

string

If set contains a date time string of the last modification date in ISO format.

name

string

Name of the API key. The name is not checked for uniqueness. Therefore multiple names with the same value can exist. Access is done via the UUID of the API key.

support_sessions

boolean

Defines whether you can manage CLI login sessions for the API key. When `true`, sessions are created and can be reviewed or revoked. When `false`, no sessions are tracked. To block access, delete or rotate the API key. Available only for user API keys.

action_when_leaked

string

Defines the action to take when API key is leaked, valid values are 'none', 'disable' and 'delete'.

expires_at

string

Date and time when the API key becomes invalid, ISO 8601 datetime in the format 'yyyy-MM-ddTHH:mm+0000'. WARNING An API key will be permanently and irrevocably deleted when both the expires_at and modified_at timestamps are more than ninety (90) days in the past, regardless of the key’s locked status or any other state.

description

string

The optional description of the API key. The 'description' property is only available if a description was provided during a create of an API key.

iam_id

string

The iam_id that this API key authenticates.

account_id

string

ID of the account that this API key authenticates for.

apikey

string

The API key value. This property only contains the API key value for the following cases: create an API key, update a service ID API key that stores the API key value as retrievable, or get a service ID API key that stores the API key value as retrievable. All other operations don't return the API key value, for example all user API key related operations, except for create, don't contain the API key value.

history

array

History of the API key.

activity

Activity

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

409 - Create Conflict - API key could not be created. Response if the Object could not be created in the persistence layer.

500 - Internal Server error. Response if unexpected error situation. happened.

GET /v1/apikeys/details

Returns the details of an API key by its value. Users can manage user API keys for themself, or service ID API keys for service IDs they have access to.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.apikey.get

Request

Path Parameters

Query Parameters

include_history

boolean

Defines if the entity history is included in the response.

Response

200 - Successful Get of API key details.

context

ResponseContext

Context with key properties for problem determination.

id

string

Unique identifier of this API Key.

entity_tag

string

Version of the API Key details object. You need to specify this value when updating the API key to avoid stale updates.

crn

string

Cloud Resource Name of the item. Example Cloud Resource Name: 'crn:v1:bluemix:public:iam-identity:us-south:a/myaccount::apikey:1234-9012-5678'

locked

boolean

The API key cannot be changed if set to true.

disabled

boolean

Defines if API key is disabled, API key cannot be used if 'disabled' is set to true.

created_at

string

If set contains a date time string of the creation date in ISO format.

created_by

string

IAM ID of the user or service which created the API key.

modified_at

string

If set contains a date time string of the last modification date in ISO format.

name

string

Name of the API key. The name is not checked for uniqueness. Therefore multiple names with the same value can exist. Access is done via the UUID of the API key.

support_sessions

boolean

Defines whether you can manage CLI login sessions for the API key. When `true`, sessions are created and can be reviewed or revoked. When `false`, no sessions are tracked. To block access, delete or rotate the API key. Available only for user API keys.

action_when_leaked

string

Defines the action to take when API key is leaked, valid values are 'none', 'disable' and 'delete'.

expires_at

string

Date and time when the API key becomes invalid, ISO 8601 datetime in the format 'yyyy-MM-ddTHH:mm+0000'. WARNING An API key will be permanently and irrevocably deleted when both the expires_at and modified_at timestamps are more than ninety (90) days in the past, regardless of the key’s locked status or any other state.

description

string

The optional description of the API key. The 'description' property is only available if a description was provided during a create of an API key.

iam_id

string

The iam_id that this API key authenticates.

account_id

string

ID of the account that this API key authenticates for.

apikey

string

The API key value. This property only contains the API key value for the following cases: create an API key, update a service ID API key that stores the API key value as retrievable, or get a service ID API key that stores the API key value as retrievable. All other operations don't return the API key value, for example all user API key related operations, except for create, don't contain the API key value.

history

array

History of the API key.

activity

Activity

400 - Parameter validation failed.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - API key not found.

500 - Internal Server error.

Get details of an API key

GET /v1/apikeys/{id}

Returns the details of an API key. Users can manage user API keys for themself, or service ID API keys for service IDs they have access to.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.apikey.get

Request

Path Parameters

id

Required *

string

Unique ID of the API key.

Query Parameters

include_history

boolean

Defines if the entity history is included in the response.

include_activity

boolean

Defines if the entity's activity is included in the response. Retrieving activity data is an expensive operation, so only request this when needed.

Response

200 - Successful Get of API key.

context

ResponseContext

Context with key properties for problem determination.

id

string

Unique identifier of this API Key.

entity_tag

string

Version of the API Key details object. You need to specify this value when updating the API key to avoid stale updates.

crn

string

Cloud Resource Name of the item. Example Cloud Resource Name: 'crn:v1:bluemix:public:iam-identity:us-south:a/myaccount::apikey:1234-9012-5678'

locked

boolean

The API key cannot be changed if set to true.

disabled

boolean

Defines if API key is disabled, API key cannot be used if 'disabled' is set to true.

created_at

string

If set contains a date time string of the creation date in ISO format.

created_by

string

IAM ID of the user or service which created the API key.

modified_at

string

If set contains a date time string of the last modification date in ISO format.

name

string

Name of the API key. The name is not checked for uniqueness. Therefore multiple names with the same value can exist. Access is done via the UUID of the API key.

support_sessions

boolean

Defines whether you can manage CLI login sessions for the API key. When `true`, sessions are created and can be reviewed or revoked. When `false`, no sessions are tracked. To block access, delete or rotate the API key. Available only for user API keys.

action_when_leaked

string

Defines the action to take when API key is leaked, valid values are 'none', 'disable' and 'delete'.

expires_at

string

Date and time when the API key becomes invalid, ISO 8601 datetime in the format 'yyyy-MM-ddTHH:mm+0000'. WARNING An API key will be permanently and irrevocably deleted when both the expires_at and modified_at timestamps are more than ninety (90) days in the past, regardless of the key’s locked status or any other state.

description

string

The optional description of the API key. The 'description' property is only available if a description was provided during a create of an API key.

iam_id

string

The iam_id that this API key authenticates.

account_id

string

ID of the account that this API key authenticates for.

apikey

string

The API key value. This property only contains the API key value for the following cases: create an API key, update a service ID API key that stores the API key value as retrievable, or get a service ID API key that stores the API key value as retrievable. All other operations don't return the API key value, for example all user API key related operations, except for create, don't contain the API key value.

history

array

History of the API key.

activity

Activity

400 - Parameter validation failed.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - API key with provided ID not found.

500 - Internal Server error.

PUT /v1/apikeys/{id}

Updates properties of an API key. This does NOT affect existing access tokens. Their token content will stay unchanged until the access token is refreshed. To update an API key, pass the property to be modified. To delete one property's value, pass the property with an empty value "". Users can manage user API keys for themself, or service ID API keys for service IDs they have access to.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.apikey.update

Auditing

Calling this method generates the following auditing event.

• iam-identity.user-apikey.update
• iam-identity.serviceid-apikey.update

Request

Request Body

UpdateApiKeyRequest

Request to update an API key.

name

string

The name of the API key to update. If specified in the request the parameter must not be empty. The name is not checked for uniqueness. Failure to this will result in an Error condition.

description

string

The description of the API key to update. If specified an empty description will clear the description of the API key. If a non empty value is provided the API key will be updated.

support_sessions

boolean

Defines whether you can manage CLI login sessions for the API key. When `true`, sessions are created and can be reviewed or revoked. When `false`, no sessions are tracked. To block access, delete or rotate the API key. Available only for user API keys.

action_when_leaked

string

Defines the action to take when API key is leaked, valid values are 'none', 'disable' and 'delete'.

expires_at

string

Date and time when the API key becomes invalid, ISO 8601 datetime in the format 'yyyy-MM-ddTHH:mm+0000'. WARNING An API key will be permanently and irrevocably deleted when both the expires_at and modified_at timestamps are more than ninety (90) days in the past, regardless of the key’s locked status or any other state.

Path Parameters

id

Required *

string

Unique ID of the API key to be updated.

Query Parameters

Response

200 - Successful - API key updated.

context

ResponseContext

Context with key properties for problem determination.

id

string

Unique identifier of this API Key.

entity_tag

string

Version of the API Key details object. You need to specify this value when updating the API key to avoid stale updates.

crn

string

Cloud Resource Name of the item. Example Cloud Resource Name: 'crn:v1:bluemix:public:iam-identity:us-south:a/myaccount::apikey:1234-9012-5678'

locked

boolean

The API key cannot be changed if set to true.

disabled

boolean

Defines if API key is disabled, API key cannot be used if 'disabled' is set to true.

created_at

string

If set contains a date time string of the creation date in ISO format.

created_by

string

IAM ID of the user or service which created the API key.

modified_at

string

If set contains a date time string of the last modification date in ISO format.

name

string

Name of the API key. The name is not checked for uniqueness. Therefore multiple names with the same value can exist. Access is done via the UUID of the API key.

support_sessions

boolean

Defines whether you can manage CLI login sessions for the API key. When `true`, sessions are created and can be reviewed or revoked. When `false`, no sessions are tracked. To block access, delete or rotate the API key. Available only for user API keys.

action_when_leaked

string

Defines the action to take when API key is leaked, valid values are 'none', 'disable' and 'delete'.

expires_at

string

Date and time when the API key becomes invalid, ISO 8601 datetime in the format 'yyyy-MM-ddTHH:mm+0000'. WARNING An API key will be permanently and irrevocably deleted when both the expires_at and modified_at timestamps are more than ninety (90) days in the past, regardless of the key’s locked status or any other state.

description

string

The optional description of the API key. The 'description' property is only available if a description was provided during a create of an API key.

iam_id

string

The iam_id that this API key authenticates.

account_id

string

ID of the account that this API key authenticates for.

apikey

string

The API key value. This property only contains the API key value for the following cases: create an API key, update a service ID API key that stores the API key value as retrievable, or get a service ID API key that stores the API key value as retrievable. All other operations don't return the API key value, for example all user API key related operations, except for create, don't contain the API key value.

history

array

History of the API key.

activity

Activity

400 - Parameter validation failed.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - API key with provided parameters not found.

409 - Conflict - there must have been an update in parallel,

the specified If-Match header does not match the current API key record. Retrieve the current API key again and apply the changes to that version.

500 - Internal Server error.

DELETE /v1/apikeys/{id}

Deletes an API key. Existing tokens will remain valid until expired. Users can manage user API keys for themself, or service ID API keys for service IDs they have access to.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.apikey.delete

Auditing

Calling this method generates the following auditing event.

• iam-identity.user-apikey.delete
• iam-identity.serviceid-apikey.delete

Request

Path Parameters

id

Required *

string

Unique ID of the API key.

Query Parameters

Response

204 - Deleted Successful - no further details.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - API key with given ID not found.

409 - Conflict - ApiKey could not be deleted.

500 - Internal Server error.

Lock the API key

POST /v1/apikeys/{id}/lock

Locks an API key by ID. Users can manage user API keys for themself, or service ID API keys for service IDs they have access to.

Auditing

Calling this method generates the following auditing event.

• iam-identity.user-apikey.update
• iam-identity.serviceid-apikey.update

Request

Path Parameters

id

Required *

string

Unique ID of the API key.

Query Parameters

Response

204 - Successful locked.

400 - Parameter validation failed.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - API key with provided ID not found.

500 - Internal Server error.

Unlock the API key

DELETE /v1/apikeys/{id}/lock

Unlocks an API key by ID. Users can manage user API keys for themself, or service ID API keys for service IDs they have access to.

Auditing

Calling this method generates the following auditing event.

• iam-identity.user-apikey.update
• iam-identity.serviceid-apikey.update

Request

Path Parameters

id

Required *

string

Unique ID of the API key.

Query Parameters

Response

204 - Successful unlocked.

400 - Parameter validation failed.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - API key with provided ID not found.

500 - Internal Server error.

Disable the API key

POST /v1/apikeys/{id}/disable

Disable an API key. Users can manage user API keys for themself, or service ID API keys for service IDs they have access to.

Auditing

Calling this method generates the following auditing event.

• iam-identity.user-apikey.update
• iam-identity.serviceid-apikey.update

Request

Path Parameters

id

Required *

string

Unique ID of the API key.

Query Parameters

Response

204 - Successful disable.

400 - Parameter validation failed.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - API key with provided ID not found.

500 - Internal Server error.

Enable the API key

DELETE /v1/apikeys/{id}/disable

Enable an API key. Users can manage user API keys for themself, or service ID API keys for service IDs they have access to.

Auditing

Calling this method generates the following auditing event.

• iam-identity.user-apikey.update
• iam-identity.serviceid-apikey.update

Request

Path Parameters

id

Required *

string

Unique ID of the API key.

Query Parameters

Response

204 - Successful enable.

400 - Parameter validation failed.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - API key with provided ID not found.

500 - Internal Server error.

GET /v1/serviceids/

Returns a list of service IDs. Users can manage user API keys for themself, or service ID API keys for service IDs they have access to. Note: apikey details are only included in the response when creating a Service ID with an api key.

Request

Path Parameters

Query Parameters

account_id

string

Account ID of the service ID(s) to query. This parameter is required (unless using a pagetoken).

group_id

string

Group ID of the service ID(s) to query. If this parameter is not provided the default group is applied.

name

string

Name of the service ID(s) to query. Optional.20 items per page. Valid range is 1 to 100.

pagesize

integer

Optional size of a single page. Default is 20 items per page. Valid range is 1 to 100.

pagetoken

string

Optional Prev or Next page token returned from a previous query execution. Default is start with first page.

sort

string

Optional sort property, valid values are name, description, created_at and modified_at. If specified, the items are sorted by the value of this property.

order

string

Optional sort order, valid values are asc and desc. Default: asc.

include_history

boolean

Defines if the entity history is included in the response.

filter

string

An optional filter query parameter used to refine the results of the search operation. For more information see Filtering list results section.

show_group_id

string

Defines if the service ID group ID is included in the response.

Response

200 - Successful response. No further actions.

context

ResponseContext

Context with key properties for problem determination.

offset

integer

The offset of the current page.

limit

integer

Optional size of a single page. Default is 20 items per page. Valid range is 1 to 100.

first

string

Link to the first page.

previous

string

Link to the previous available page. If 'previous' property is not part of the response no previous page is available.

next

string

Link to the next available page. If 'next' property is not part of the response no next page is available.

serviceids

array

List of service IDs based on the query paramters and the page size. The service IDs array is always part of the response but might be empty depending on the query parameter values provided.

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

500 - Internal Server error. Response if unexpected error situation happened.

POST /v1/serviceids/

Creates a service ID for an IBM Cloud account. Users can manage user API keys for themself, or service ID API keys for service IDs they have access to.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.serviceid.create

Auditing

Calling this method generates the following auditing event.

• iam-identity.account-serviceid.create

Request

Request Body

CreateServiceIdRequest

Request to create a service ID.

account_id

Required *

string

ID of the account the service ID belongs to.

group_id

string

ID of the group to which the service ID belongs to. If the value is not set, the service ID is bound to the default group.

name

Required *

string

Name of the Service Id. The name is not checked for uniqueness. Therefore multiple names with the same value can exist. Access is done via the UUID of the Service Id.

description

string

The optional description of the Service Id. The 'description' property is only available if a description was provided during a create of a Service Id.

unique_instance_crns

array

Optional list of CRNs (string array) which point to the services connected to the service ID.

apikey

ApiKeyInsideCreateServiceIdRequest

Parameters for the API key in the Create service Id V1 REST request.

name

Required *

string

Name of the API key. The name is not checked for uniqueness. Therefore multiple names with the same value can exist. Access is done via the UUID of the API key.

description

string

The optional description of the API key. The 'description' property is only available if a description was provided during a create of an API key.

apikey

string

You can optionally passthrough the API key value for this API key. If passed, a minimum length validation of 32 characters for that apiKey value is done, i.e. the value can contain any characters and can even be non-URL safe, but the minimum length requirement must be met. If omitted, the API key management will create an URL safe opaque API key value. The value of the API key is checked for uniqueness. Ensure enough variations when passing in this value.

store_value

boolean

Send true or false to set whether the API key value is retrievable in the future by using the Get details of an API key request. If you create an API key for a user, you must specify `false` or omit the value. We don't allow storing of API keys for users.

action_when_leaked

string

Defines the action to take when API key is leaked, valid values are 'none', 'disable' and 'delete'.

expires_at

string

Date and time when the API key becomes invalid, ISO 8601 datetime in the format 'yyyy-MM-ddTHH:mm+0000'. WARNING An API key will be permanently and irrevocably deleted when both the expires_at and modified_at timestamps are more than ninety (90) days in the past, regardless of the key’s locked status or any other state.

Path Parameters

Query Parameters

show_group_id

string

Defines if the service ID group ID is included in the response.

Response

201 - Service ID successfully created.

context

ResponseContext

Context with key properties for problem determination.

id

string

Unique identifier of this Service Id.

iam_id

string

Cloud wide identifier for identities of this service ID.

entity_tag

string

Version of the service ID details object. You need to specify this value when updating the service ID to avoid stale updates.

crn

string

Cloud Resource Name of the item. Example Cloud Resource Name: 'crn:v1:bluemix:public:iam-identity:us-south:a/myaccount::serviceid:1234-5678-9012'

locked

boolean

The service ID cannot be changed if set to true.

created_at

string

If set contains a date time string of the creation date in ISO format.

modified_at

string

If set contains a date time string of the last modification date in ISO format.

account_id

string

ID of the account the service ID belongs to.

group_id

string

ID of the group to which the service ID belongs to. Only set if requested via parameter `show_group_id`.

name

string

Name of the Service Id. The name is not checked for uniqueness. Therefore multiple names with the same value can exist. Access is done via the UUID of the Service Id.

description

string

The optional description of the Service Id. The 'description' property is only available if a description was provided during a create of a Service Id.

unique_instance_crns

array

Optional list of CRNs (string array) which point to the services connected to the service ID.

history

array

History of the Service ID.

apikey

ApiKey

Response body format for API key V1 REST requests.

activity

Activity

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

409 - Create Conflict - service ID could not be created. Response if the Object could not be created in the persistence layer.

500 - Internal Server error. Response if unexpected error situation happened.

GET /v1/serviceids/{id}

Returns the details of a service ID. Users can manage user API keys for themself, or service ID API keys for service IDs they have access to. Note: apikey details are only included in the response when creating a Service ID with an api key.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.serviceid.get

Request

Path Parameters

id

Required *

string

Unique ID of the service ID.

Query Parameters

include_history

boolean

Defines if the entity history is included in the response.

include_activity

boolean

Defines if the entity's activity is included in the response. Retrieving activity data is an expensive operation, so only request this when needed.

show_group_id

string

Defines if the service ID group ID is included in the response.

Response

200 - Successful response. No further actions.

context

ResponseContext

Context with key properties for problem determination.

id

string

Unique identifier of this Service Id.

iam_id

string

Cloud wide identifier for identities of this service ID.

entity_tag

string

Version of the service ID details object. You need to specify this value when updating the service ID to avoid stale updates.

crn

string

Cloud Resource Name of the item. Example Cloud Resource Name: 'crn:v1:bluemix:public:iam-identity:us-south:a/myaccount::serviceid:1234-5678-9012'

locked

boolean

The service ID cannot be changed if set to true.

created_at

string

If set contains a date time string of the creation date in ISO format.

modified_at

string

If set contains a date time string of the last modification date in ISO format.

account_id

string

ID of the account the service ID belongs to.

group_id

string

ID of the group to which the service ID belongs to. Only set if requested via parameter `show_group_id`.

name

string

Name of the Service Id. The name is not checked for uniqueness. Therefore multiple names with the same value can exist. Access is done via the UUID of the Service Id.

description

string

The optional description of the Service Id. The 'description' property is only available if a description was provided during a create of a Service Id.

unique_instance_crns

array

Optional list of CRNs (string array) which point to the services connected to the service ID.

history

array

History of the Service ID.

apikey

ApiKey

Response body format for API key V1 REST requests.

activity

Activity

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - service ID with provided ID not found.

500 - Internal Server error. Response if unexpected error situation happened.

PUT /v1/serviceids/{id}

Updates properties of a service ID. This does NOT affect existing access tokens. Their token content will stay unchanged until the access token is refreshed. To update a service ID, pass the property to be modified. To delete one property's value, pass the property with an empty value "".Users can manage user API keys for themself, or service ID API keys for service IDs they have access to. Note: apikey details are only included in the response when creating a Service ID with an apikey.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.serviceid.update

Auditing

Calling this method generates the following auditing event.

• iam-identity.account-serviceid.update

Request

Request Body

UpdateServiceIdRequest

Request to update a service ID.

name

string

The name of the service ID to update. If specified in the request the parameter must not be empty. The name is not checked for uniqueness. Failure to this will result in an Error condition.

description

string

The description of the service ID to update. If specified an empty description will clear the description of the service ID. If an non empty value is provided the service ID will be updated.

unique_instance_crns

array

List of CRNs which point to the services connected to this service ID. If specified an empty list will clear all existing unique instance crns of the service ID.

Path Parameters

id

Required *

string

Unique ID of the service ID to be updated.

Query Parameters

show_group_id

string

Defines if the service ID group ID is included in the response.

Response

200 - Successful - service ID updated.

context

ResponseContext

Context with key properties for problem determination.

id

string

Unique identifier of this Service Id.

iam_id

string

Cloud wide identifier for identities of this service ID.

entity_tag

string

Version of the service ID details object. You need to specify this value when updating the service ID to avoid stale updates.

crn

string

Cloud Resource Name of the item. Example Cloud Resource Name: 'crn:v1:bluemix:public:iam-identity:us-south:a/myaccount::serviceid:1234-5678-9012'

locked

boolean

The service ID cannot be changed if set to true.

created_at

string

If set contains a date time string of the creation date in ISO format.

modified_at

string

If set contains a date time string of the last modification date in ISO format.

account_id

string

ID of the account the service ID belongs to.

group_id

string

ID of the group to which the service ID belongs to. Only set if requested via parameter `show_group_id`.

name

string

Name of the Service Id. The name is not checked for uniqueness. Therefore multiple names with the same value can exist. Access is done via the UUID of the Service Id.

description

string

The optional description of the Service Id. The 'description' property is only available if a description was provided during a create of a Service Id.

unique_instance_crns

array

Optional list of CRNs (string array) which point to the services connected to the service ID.

history

array

History of the Service ID.

apikey

ApiKey

Response body format for API key V1 REST requests.

activity

Activity

400 - Parameter validation failed.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Service ID with provided parameters not found

409 - Conflict - there must have been an update in parallel, the specified If-Match header does not match the current service ID record. Retrieve the current service ID again and apply the changes to that version.

500 - Internal Server error.

DELETE /v1/serviceids/{id}

Deletes a service ID and all API keys associated to it. Before deleting the service ID, all associated API keys are deleted. In case a Delete Conflict (status code 409) a retry of the request may help as the service ID is only deleted if the associated API keys were successfully deleted before. Users can manage user API keys for themself, or service ID API keys for service IDs they have access to.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.serviceid.delete

Auditing

Calling this method generates the following auditing event.

• iam-identity.account-serviceid.delete

Request

Path Parameters

id

Required *

string

Unique ID of the service ID.

Query Parameters

Response

204 - service ID successfully deleted. Response if the Object was successfully deleted from the persistence layer.

400 - The service ID is locked.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - service ID with provided ID not found.

409 - Delete Conflict - service ID could not be deleted. Response if the Object could not be deleted from the persistence layer.

500 - Internal Server error. Response if unexpected error situation happened.

Lock the service ID

POST /v1/serviceids/{id}/lock

Locks a service ID by ID. Users can manage user API keys for themself, or service ID API keys for service IDs they have access to.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.serviceid.update

Auditing

Calling this method generates the following auditing event.

• iam-identity.account-serviceid.update

Request

Path Parameters

id

Required *

string

Unique ID of the service ID.

Query Parameters

Response

204 - Successful locked.

400 - Parameter validation failed.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Service ID with provided uuid not found.

500 - Internal Server error.

Unlock the service ID

DELETE /v1/serviceids/{id}/lock

Unlocks a service ID by ID. Users can manage user API keys for themself, or service ID API keys for service IDs they have access to.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.serviceid.update

Auditing

Calling this method generates the following auditing event.

• iam-identity.account-serviceid.update

Request

Path Parameters

id

Required *

string

Unique ID of the service ID.

Query Parameters

Response

204 - Successful unlocked.

400 - Parameter validation failed.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Service ID with provided uuid not found.

500 - Internal Server error.

Create a trusted profile

POST /v1/profiles

Create a trusted profile for a given account ID.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile.create

Auditing

Calling this method generates the following auditing event.

• iam-identity.profile.create

Request

Request Body

CreateTrustedProfileRequest

Request to create a trusted profile.

name

Required *

string

Name of the trusted profile. The name is checked for uniqueness. Therefore trusted profiles with the same names can not exist in the same account.

description

string

The optional description of the trusted profile. The 'description' property is only available if a description was provided during creation of trusted profile.

account_id

Required *

string

The account ID of the trusted profile.

email

string

The email of the trusted profile.

Path Parameters

Query Parameters

Response

201 - Trusted profile successfully created. Response if the Object could be created in the persistence layer.

context

ResponseContext

Context with key properties for problem determination.

id

string

the unique identifier of the trusted profile. Example:'Profile-94497d0d-2ac3-41bf-a993-a49d1b14627c'

entity_tag

string

Version of the trusted profile details object. You need to specify this value when updating the trusted profile to avoid stale updates.

crn

string

Cloud Resource Name of the item. Example Cloud Resource Name: 'crn:v1:bluemix:public:iam-identity:us-south:a/myaccount::profile:Profile-94497d0d-2ac3-41bf-a993-a49d1b14627c'

name

string

Name of the trusted profile. The name is checked for uniqueness. Therefore trusted profiles with the same names can not exist in the same account.

description

string

The optional description of the trusted profile. The 'description' property is only available if a description was provided during a create of a trusted profile.

email

string

The optional email of the trusted profile. The 'email' property is only available if an email was provided during a create of a trusted profile.

created_at

string

If set contains a date time string of the creation date in ISO format.

modified_at

string

If set contains a date time string of the last modification date in ISO format.

iam_id

string

The iam_id of this trusted profile.

account_id

string

ID of the account that this trusted profile belong to.

template_id

string

ID of the IAM template that was used to create an enterprise-managed trusted profile in your account. When returned, this indicates that the trusted profile is created from and managed by a template in the root enterprise account.

assignment_id

string

ID of the assignment that was used to create an enterprise-managed trusted profile in your account. When returned, this indicates that the trusted profile is created from and managed by a template in the root enterprise account.

ims_account_id

integer

IMS acount ID of the trusted profile

ims_user_id

integer

IMS user ID of the trusted profile

history

array

History of the trusted profile.

activity

Activity

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

409 - Create Conflict - Trusted profile could not be created. Response if the Object could not be created in the persistence layer.

500 - Internal Server error.

List trusted profiles

GET /v1/profiles

List the trusted profiles in an account. The `account_id` query parameter determines the account from which to retrieve the list of trusted profiles.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile.get

Auditing

Calling this method generates the following auditing event.

• iam-identity.profile.get

Request

Path Parameters

Query Parameters

account_id

Required *

string

Account ID to query for trusted profiles.

name

string

Name of the trusted profile to query.

pagesize

integer

Optional size of a single page. Default is 20 items per page. Valid range is 1 to 100.

sort

string

Optional sort property, valid values are name, description, created_at and modified_at. If specified, the items are sorted by the value of this property.

order

string

Optional sort order, valid values are asc and desc. Default: asc.

include_history

boolean

Defines if the entity history is included in the response.

pagetoken

string

Optional Prev or Next page token returned from a previous query execution. Default is start with first page.

filter

string

An optional filter query parameter used to refine the results of the search operation. For more information see Filtering list results section.

Response

200 - Successful operation.

context

ResponseContext

Context with key properties for problem determination.

offset

integer

The offset of the current page.

limit

integer

Optional size of a single page. Default is 20 items per page. Valid range is 1 to 100

first

string

Link to the first page.

previous

string

Link to the previous available page. If 'previous' property is not part of the response no previous page is available.

next

string

Link to the next available page. If 'next' property is not part of the response no next page is available.

profiles

array

List of trusted profiles

400 - Parameter validation failed.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

401 - The incoming request did not contain a valid authentication information.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

404 - account_id does not match Authorization token, account_id not found.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

500 - Internal Server error.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

Get a trusted profile

GET /v1/profiles/{profile-id}

Retrieve a trusted profile by its `profile-id`. Only the trusted profile's data is returned (`name`, `description`, `iam_id`, etc.), not the federated users or compute resources that qualify to apply the trusted profile.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile.get

Auditing

Calling this method generates the following auditing event.

• iam-identity.profile.get

Request

Path Parameters

profile-id

Required *

string

ID of the trusted profile to get.

Query Parameters

include_activity

boolean

Defines if the entity's activity is included in the response. Retrieving activity data is an expensive operation, so only request this when needed.

Response

200 - Successful - Get of Trusted profile.

context

ResponseContext

Context with key properties for problem determination.

id

string

the unique identifier of the trusted profile. Example:'Profile-94497d0d-2ac3-41bf-a993-a49d1b14627c'

entity_tag

string

Version of the trusted profile details object. You need to specify this value when updating the trusted profile to avoid stale updates.

crn

string

Cloud Resource Name of the item. Example Cloud Resource Name: 'crn:v1:bluemix:public:iam-identity:us-south:a/myaccount::profile:Profile-94497d0d-2ac3-41bf-a993-a49d1b14627c'

name

string

Name of the trusted profile. The name is checked for uniqueness. Therefore trusted profiles with the same names can not exist in the same account.

description

string

The optional description of the trusted profile. The 'description' property is only available if a description was provided during a create of a trusted profile.

email

string

The optional email of the trusted profile. The 'email' property is only available if an email was provided during a create of a trusted profile.

created_at

string

If set contains a date time string of the creation date in ISO format.

modified_at

string

If set contains a date time string of the last modification date in ISO format.

iam_id

string

The iam_id of this trusted profile.

account_id

string

ID of the account that this trusted profile belong to.

template_id

string

ID of the IAM template that was used to create an enterprise-managed trusted profile in your account. When returned, this indicates that the trusted profile is created from and managed by a template in the root enterprise account.

assignment_id

string

ID of the assignment that was used to create an enterprise-managed trusted profile in your account. When returned, this indicates that the trusted profile is created from and managed by a template in the root enterprise account.

ims_account_id

integer

IMS acount ID of the trusted profile

ims_user_id

integer

IMS user ID of the trusted profile

history

array

History of the trusted profile.

activity

Activity

400 - Parameter validation failed.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Trusted profile with provided parameters not found.

500 - Internal Server error.

Update a trusted profile

PUT /v1/profiles/{profile-id}

Update the name or description of an existing trusted profile.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile.update

Auditing

Calling this method generates the following auditing event.

• iam-identity.profile.update

Request

Request Body

UpdateTrustedProfileRequest

Request to update a trusted profile.

name

string

The name of the trusted profile to update. If specified in the request the parameter must not be empty. The name is checked for uniqueness. Failure to this will result in an Error condition.

description

string

The description of the trusted profile to update. If specified an empty description will clear the description of the trusted profile. If a non empty value is provided the trusted profile will be updated.

email

string

The email of the profile to update. If specified an empty email will clear the email of the profile. If an non empty value is provided the trusted profile will be updated.

Path Parameters

profile-id

Required *

string

ID of the trusted profile to be updated.

Query Parameters

Response

200 - Successful - Trusted profile updated.

context

ResponseContext

Context with key properties for problem determination.

id

string

the unique identifier of the trusted profile. Example:'Profile-94497d0d-2ac3-41bf-a993-a49d1b14627c'

entity_tag

string

Version of the trusted profile details object. You need to specify this value when updating the trusted profile to avoid stale updates.

crn

string

Cloud Resource Name of the item. Example Cloud Resource Name: 'crn:v1:bluemix:public:iam-identity:us-south:a/myaccount::profile:Profile-94497d0d-2ac3-41bf-a993-a49d1b14627c'

name

string

Name of the trusted profile. The name is checked for uniqueness. Therefore trusted profiles with the same names can not exist in the same account.

description

string

The optional description of the trusted profile. The 'description' property is only available if a description was provided during a create of a trusted profile.

email

string

The optional email of the trusted profile. The 'email' property is only available if an email was provided during a create of a trusted profile.

created_at

string

If set contains a date time string of the creation date in ISO format.

modified_at

string

If set contains a date time string of the last modification date in ISO format.

iam_id

string

The iam_id of this trusted profile.

account_id

string

ID of the account that this trusted profile belong to.

template_id

string

ID of the IAM template that was used to create an enterprise-managed trusted profile in your account. When returned, this indicates that the trusted profile is created from and managed by a template in the root enterprise account.

assignment_id

string

ID of the assignment that was used to create an enterprise-managed trusted profile in your account. When returned, this indicates that the trusted profile is created from and managed by a template in the root enterprise account.

ims_account_id

integer

IMS acount ID of the trusted profile

ims_user_id

integer

IMS user ID of the trusted profile

history

array

History of the trusted profile.

activity

Activity

400 - Parameter validation failed.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Trusted profile with provided parameters not found.

409 - Conflict - there must have been an update in parallel,

the specified If-Match header does not match the current Trusted profile record. Retrieve the current Trusted profile again and apply the changes to that version.

500 - Internal Server error.

Delete a trusted profile

DELETE /v1/profiles/{profile-id}

Delete a trusted profile. When you delete trusted profile, compute resources and federated users are unlinked from the profile and can no longer apply the trusted profile identity.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile.delete

Auditing

Calling this method generates the following auditing event.

• iam-identity.profile.delete

Request

Path Parameters

profile-id

Required *

string

ID of the trusted profile.

Query Parameters

Response

204 - Deleted Successful - no further details.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Trusted profile with given ID not found.

409 - Conflict - Trusted profile could not be deleted.

500 - Internal Server error.

Create claim rule for a trusted profile

POST /v1/profiles/{profile-id}/rules

Create a claim rule for a trusted profile. There is a limit of 20 rules per trusted profile.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile.update

Auditing

Calling this method generates the following auditing event.

• iam-identity.profile.update

Request

Request Body

ProfileClaimRuleRequest

Request to create a claim rule for trusted profile.

context

ResponseContext

Context with key properties for problem determination.

transaction_id

string

The transaction ID of the inbound REST request.

operation

string

The operation of the inbound REST request.

user_agent

string

The user agent of the inbound REST request.

url

string

The URL of that cluster.

instance_id

string

The instance ID of the server instance processing the request.

thread_id

string

The thread ID of the server instance processing the request.

host

string

The host of the server instance processing the request.

start_time

string

The start time of the request.

end_time

string

The finish time of the request.

elapsed_time

string

The elapsed time in msec.

cluster_name

string

The cluster name.

name

string

Name of the claim rule to be created or updated

type

Required *

string

Type of the claim rule, either 'Profile-SAML' or 'Profile-CR'

realm_name

string

The realm name of the Idp this claim rule applies to. This field is required only if the type is specified as 'Profile-SAML'.

cr_type

string

The compute resource type the rule applies to, required only if type is specified as 'Profile-CR'. Valid values are VSI, PVS, BMS, IKS_SA, ROKS_SA, CE.

expiration

integer

Session expiration in seconds, only required if type is 'Profile-SAML'.

conditions

Required *

array

Conditions of this claim rule.

Path Parameters

profile-id

Required *

string

ID of the trusted profile to create a claim rule.

Query Parameters

Response

201 - Successful operation.

id

string

the unique identifier of the claim rule

entity_tag

string

version of the claim rule

created_at

string

If set contains a date time string of the creation date in ISO format.

modified_at

string

If set contains a date time string of the last modification date in ISO format.

name

string

The optional claim rule name

type

string

Type of the claim rule, either 'Profile-SAML' or 'Profile-CR'

realm_name

string

The realm name of the Idp this claim rule applies to

expiration

integer

Session expiration in seconds

cr_type

string

The compute resource type. Not required if type is Profile-SAML. Valid values are VSI, PVS, BMS, IKS_SA, ROKS_SA, CE.

conditions

array

Conditions of this claim rule.

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

409 - Create Conflict - Claim rule could not be created. Response if the Object could not be created in the persistence layer.

500 - Internal Server error.

List claim rules for a trusted profile

GET /v1/profiles/{profile-id}/rules

Get a list of all claim rules for a trusted profile. The `profile-id` query parameter determines the profile from which to retrieve the list of claim rules.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile.get

Auditing

Calling this method generates the following auditing event.

• iam-identity.profile.get

Request

Path Parameters

profile-id

Required *

string

ID of the trusted profile.

Query Parameters

Response

200 - Successful operation.

context

ResponseContext

Context with key properties for problem determination.

rules

array

List of claim rules

400 - Parameter validation failed.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

401 - The incoming request did not contain a valid authentication information.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

404 - Trusted profile ID does not match Authorization token, Trusted profile ID not found.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

500 - Internal Server error.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

Get a claim rule for a trusted profile

GET /v1/profiles/{profile-id}/rules/{rule-id}

A specific claim rule can be fetched for a given trusted profile ID and rule ID.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile.get

Auditing

Calling this method generates the following auditing event.

• iam-identity.profile.get

Request

Path Parameters

profile-id

Required *

string

ID of the trusted profile.

rule-id

Required *

string

ID of the claim rule to get.

Query Parameters

Response

200 - Successful - Get of Claim rule.

id

string

the unique identifier of the claim rule

entity_tag

string

version of the claim rule

created_at

string

If set contains a date time string of the creation date in ISO format.

modified_at

string

If set contains a date time string of the last modification date in ISO format.

name

string

The optional claim rule name

type

string

Type of the claim rule, either 'Profile-SAML' or 'Profile-CR'

realm_name

string

The realm name of the Idp this claim rule applies to

expiration

integer

Session expiration in seconds

cr_type

string

The compute resource type. Not required if type is Profile-SAML. Valid values are VSI, PVS, BMS, IKS_SA, ROKS_SA, CE.

conditions

array

Conditions of this claim rule.

400 - Parameter validation failed.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Claim rule with provided parameters not found.

500 - Internal Server error.

Update claim rule for a trusted profile

PUT /v1/profiles/{profile-id}/rules/{rule-id}

Update a specific claim rule for a given trusted profile ID and rule ID.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile.update

Auditing

Calling this method generates the following auditing event.

• iam-identity.profile.update

Request

Request Body

ProfileClaimRuleRequest

Request to update a claim rule.

context

ResponseContext

Context with key properties for problem determination.

transaction_id

string

The transaction ID of the inbound REST request.

operation

string

The operation of the inbound REST request.

user_agent

string

The user agent of the inbound REST request.

url

string

The URL of that cluster.

instance_id

string

The instance ID of the server instance processing the request.

thread_id

string

The thread ID of the server instance processing the request.

host

string

The host of the server instance processing the request.

start_time

string

The start time of the request.

end_time

string

The finish time of the request.

elapsed_time

string

The elapsed time in msec.

cluster_name

string

The cluster name.

name

string

Name of the claim rule to be created or updated

type

Required *

string

Type of the claim rule, either 'Profile-SAML' or 'Profile-CR'

realm_name

string

The realm name of the Idp this claim rule applies to. This field is required only if the type is specified as 'Profile-SAML'.

cr_type

string

The compute resource type the rule applies to, required only if type is specified as 'Profile-CR'. Valid values are VSI, PVS, BMS, IKS_SA, ROKS_SA, CE.

expiration

integer

Session expiration in seconds, only required if type is 'Profile-SAML'.

conditions

Required *

array

Conditions of this claim rule.

Path Parameters

profile-id

Required *

string

ID of the trusted profile.

rule-id

Required *

string

ID of the claim rule to update.

Query Parameters

Response

200 - Successful - Claim rule updated.

id

string

the unique identifier of the claim rule

entity_tag

string

version of the claim rule

created_at

string

If set contains a date time string of the creation date in ISO format.

modified_at

string

If set contains a date time string of the last modification date in ISO format.

name

string

The optional claim rule name

type

string

Type of the claim rule, either 'Profile-SAML' or 'Profile-CR'

realm_name

string

The realm name of the Idp this claim rule applies to

expiration

integer

Session expiration in seconds

cr_type

string

The compute resource type. Not required if type is Profile-SAML. Valid values are VSI, PVS, BMS, IKS_SA, ROKS_SA, CE.

conditions

array

Conditions of this claim rule.

400 - Parameter validation failed.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Claim rule with provided parameters not found.

409 - Conflict - there must have been an update in parallel,

the specified If-Match header does not match the current claim rule record. Retrieve the current claim rule again and apply the changes to that version.

500 - Internal Server error.

Delete a claim rule

DELETE /v1/profiles/{profile-id}/rules/{rule-id}

Delete a claim rule. When you delete a claim rule, federated user or compute resources are no longer required to meet the conditions of the claim rule in order to apply the trusted profile.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile.update

Auditing

Calling this method generates the following auditing event.

• iam-identity.profile.update

Request

Path Parameters

profile-id

Required *

string

ID of the trusted profile.

rule-id

Required *

string

ID of the claim rule to delete.

Query Parameters

Response

204 - Deleted Successful - no further details.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Claim rule with given ID not found.

409 - Conflict - Claim rule could not be deleted.

500 - Internal Server error.

Create link to a trusted profile

POST /v1/profiles/{profile-id}/links

Create a direct link between a specific compute resource and a trusted profile, rather than creating conditions that a compute resource must fulfill to apply a trusted profile.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile.update
• iam-identity.profile.linkToResource

Auditing

Calling this method generates the following auditing event.

• iam-identity.profile.update

Request

Request Body

CreateProfileLinkRequest

Request to create a Link to Trusted profile.

name

string

Optional name of the Link

cr_type

Required *

string

The compute resource type. Valid values are VSI, PVS, BMS, IKS_SA, ROKS_SA, CE

is_cross_account

boolean

Flag to indicate that the link provides cross account access. If not provided then the account scope of the CRN must match the Profile's account

link

Required *

object

Link details

crn

Required *

string

The CRN of the compute resource

namespace

string

The compute resource namespace, only required if cr_type is IKS_SA or ROKS_SA

name

string

Name of the compute resource, only required if cr_type is IKS_SA or ROKS_SA

component_type

string

Component type of the compute resource, only required if cr_type is CE

component_name

string

Component name of the compute resource, only required if cr_type is CE

Path Parameters

profile-id

Required *

string

ID of the trusted profile.

Query Parameters

Response

201 - Link successfully created for trusted profile. Response if the Object could be created in the persistence layer.

id

string

the unique identifier of the link

entity_tag

string

version of the link

created_at

string

If set contains a date time string of the creation date in ISO format.

modified_at

string

If set contains a date time string of the last modification date in ISO format.

name

string

Optional name of the Link

cr_type

string

The compute resource type. Valid values are VSI, PVS, BMS, IKS_SA, ROKS_SA, CE

is_cross_account

boolean

Flag to indicate that the link provides cross account access. If not provided then the account scope of the CRN must match the Profile's account

link

object

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

409 - Create Conflict - Link could not be created. Response if the Object could not be created in the persistence layer.

500 - Internal Server error. Response if unexpected error situation. happened.

List links to a trusted profile

GET /v1/profiles/{profile-id}/links

Get a list of links to a trusted profile.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile.get
• iam-identity.profile.linkToResource

Auditing

Calling this method generates the following auditing event.

• iam-identity.profile.get

Request

Path Parameters

profile-id

Required *

string

ID of the trusted profile

Query Parameters

Response

200 - Successful - Get list of link to a trusted profile

links

array

List of links to a trusted profile

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - profile with provided ID not found.

500 - Internal Server error.

Delete compute resource link to profile by given parameters.

DELETE /v1/profiles/{profile-id}/links

Deletes compute resource link of a Trusted Profile matching the given parameters.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile.update
• iam-identity.profile.linkToResource

Auditing

Calling this method generates the following auditing event.

• iam-identity.profile.update

Request

Path Parameters

profile-id

Required *

string

The unique ID of the Trusted Profile

Query Parameters

type

Required *

string

The compute resource type. Valid values are VSI, PVS, BMS, IKS_SA, ROKS_SA, CE

crn

string

CRN of the compute resource (VSI/PVS/BMS/IKS/ROKS/CE)

namespace

string

Namespace of the compute resource (IKS/ROKS).

name

string

Name of the compute resource (IKS/ROKS).

component_type

string

Component type of the compute resource, only required if type is CE

component_name

string

Component name of the compute resource, only required if type is CE

Response

204 - Deleted Successful - no further details.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Link with given ID not found.

409 - Conflict - Link could not be deleted.

500 - Internal Server error.

Get link to a trusted profile

GET /v1/profiles/{profile-id}/links/{link-id}

Get a specific link to a trusted profile by `link_id`.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile.get
• iam-identity.profile.linkToResource

Auditing

Calling this method generates the following auditing event.

• iam-identity.profile.get

Request

Path Parameters

profile-id

Required *

string

ID of the trusted profile

link-id

Required *

string

ID of the link

Query Parameters

Response

200 - Successful - Get of link to a trusted profile

id

string

the unique identifier of the link

entity_tag

string

version of the link

created_at

string

If set contains a date time string of the creation date in ISO format.

modified_at

string

If set contains a date time string of the last modification date in ISO format.

name

string

Optional name of the Link

cr_type

string

The compute resource type. Valid values are VSI, PVS, BMS, IKS_SA, ROKS_SA, CE

is_cross_account

boolean

Flag to indicate that the link provides cross account access. If not provided then the account scope of the CRN must match the Profile's account

link

object

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Link with provided ID not found.

500 - Internal Server error.

Delete link to a trusted profile

DELETE /v1/profiles/{profile-id}/links/{link-id}

Delete a link between a compute resource and a trusted profile.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile.update
• iam-identity.profile.linkToResource

Auditing

Calling this method generates the following auditing event.

• iam-identity.profile.update

Request

Path Parameters

profile-id

Required *

string

ID of the trusted profile

link-id

Required *

string

ID of the link

Query Parameters

Response

204 - Deleted Successful - no further details.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Link with given ID not found.

409 - Conflict - Link could not be deleted.

500 - Internal Server error.

Get a list of identities that can assume the trusted profile

GET /v1/profiles/{profile-id}/identities

Get a list of identities that can assume the trusted profile

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile.get

Auditing

Calling this method generates the following auditing event.

• iam-identity.profile.get

Request

Path Parameters

profile-id

Required *

string

ID of the trusted profile.

Query Parameters

Response

200 - Successful response with identities

entity_tag

string

Entity tag of the profile identities response

identities

array

List of identities

400 - Parameter validation failed.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Profile not found.

500 - Internal Server error.

Update the list of identities that can assume the trusted profile

PUT /v1/profiles/{profile-id}/identities

Update the list of identities that can assume the trusted profile

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile.update

Auditing

Calling this method generates the following auditing event.

• iam-identity.profile.update

Request

Request Body

ProfileIdentitiesUpdateRequest

Request to update identities.

identities

array

List of identities that can assume the trusted profile

Path Parameters

profile-id

Required *

string

ID of the trusted profile.

Query Parameters

Response

200 - Successful response with identities

entity_tag

string

Entity tag of the profile identities response

identities

array

List of identities

400 - Parameter validation failed.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Profile not found.

500 - Internal Server error.

POST /v1/profiles/{profile-id}/identities/{identity-type}

Add a specific identity that can assume the trusted profile.

Note: This API will update the trusted profile itself, thus calling it repeatedly for the same profile can lead to conflicts responded with HTTP code 409. Make sure to call this API only once in a few seconds for the same trusted profile.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile.update

Auditing

Calling this method generates the following auditing event.

• iam-identity.profile.update

Request

Request Body

ProfileIdentityRequest

Request to update identities.

identifier

Required *

string

Identifier of the identity that can assume the trusted profiles. This can be a user identifier (IAM id), serviceid or crn. Internally it uses account id of the service id for the identifier 'serviceid' and for the identifier 'crn' it uses account id contained in the CRN.

type

Required *

string

Type of the identity

accounts

array

Only valid for the type user. Accounts from which a user can assume the trusted profile.

description

string

Description of the identity that can assume the trusted profile. This is optional field for all the types of identities. When this field is not set for the identity type 'serviceid' then the description of the service id is used. Description is recommended for the identity type 'crn' E.g. 'Instance 1234 of IBM Cloud Service project'

Path Parameters

profile-id

Required *

string

ID of the trusted profile

identity-type

Required *

string

Type of the identity

Query Parameters

Response

200 - Successful response with identities

iam_id

string

IAM ID of the identity

identifier

string

Identifier of the identity that can assume the trusted profiles. This can be a user identifier (IAM id), serviceid or crn. Internally it uses account id of the service id for the identifier 'serviceid' and for the identifier 'crn' it uses account id contained in the CRN.

type

string

Type of the identity

accounts

array

Only valid for the type user. Accounts from which a user can assume the trusted profile.

description

string

Description of the identity that can assume the trusted profile. This is optional field for all the types of identities. When this field is not set for the identity type 'serviceid' then the description of the service id is used. Description is recommended for the identity type 'crn' E.g. 'Instance 1234 of IBM Cloud Service project'

400 - Parameter validation failed.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Profile not found.

409 - Conflict updating the trusted profile. The API was called several times in quick succession for the same trusted profile.

500 - Internal Server error.

Get the identity that can assume the trusted profile

GET /v1/profiles/{profile-id}/identities/{identity-type}/{identifier-id}

Get the identity that can assume the trusted profile

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile.get

Auditing

Calling this method generates the following auditing event.

• iam-identity.profile.get

Request

Path Parameters

profile-id

Required *

string

ID of the trusted profile

identity-type

Required *

string

Type of the identity

identifier-id

Required *

string

Identifier of the identity that can assume the trusted profiles.

Query Parameters

Response

200 - Successful response with identities

iam_id

string

IAM ID of the identity

identifier

string

Identifier of the identity that can assume the trusted profiles. This can be a user identifier (IAM id), serviceid or crn. Internally it uses account id of the service id for the identifier 'serviceid' and for the identifier 'crn' it uses account id contained in the CRN.

type

string

Type of the identity

accounts

array

Only valid for the type user. Accounts from which a user can assume the trusted profile.

description

string

Description of the identity that can assume the trusted profile. This is optional field for all the types of identities. When this field is not set for the identity type 'serviceid' then the description of the service id is used. Description is recommended for the identity type 'crn' E.g. 'Instance 1234 of IBM Cloud Service project'

400 - Parameter validation failed.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Profile not found.

500 - Internal Server error.

DELETE /v1/profiles/{profile-id}/identities/{identity-type}/{identifier-id}

Delete the identity that can assume the trusted profile.

Note: This API will update the trusted profile itself, thus calling it repeatedly for the same profile can lead to conflicts responded with HTTP code 409. Make sure to call this API only once in a few seconds for the same trusted profile.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile.update

Auditing

Calling this method generates the following auditing event.

• iam-identity.profile.update

Request

Path Parameters

profile-id

Required *

string

ID of the trusted profile

identity-type

Required *

string

Type of the identity

identifier-id

Required *

string

Identifier of the identity that can assume the trusted profiles.

Query Parameters

Response

204 - Deleted Successful - no further details.

400 - Parameter validation failed.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Profile not found.

409 - Conflict updating the trusted profile. The API was called several times in quick succession for the same trusted profile.

500 - Internal Server error.

Trigger activity report for the account

POST /v1/activity/accounts/{account_id}/report

Trigger activity report for the account by specifying the account ID. It can take a few minutes to generate the report for retrieval.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.report.create

Request

Path Parameters

account_id

Required *

string

ID of the account

Query Parameters

type

string

Optional report type. The supported value is 'inactive'. List all identities that have not authenticated within the time indicated by duration.

duration

string

Optional duration of the report. The supported unit of duration is hours.

Response

202 - Create report accepted.

reference

string

Reference for the report to be generated.

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

500 - Internal Server error. Response if unexpected error situation happened.

Get activity report for the account

GET /v1/activity/accounts/{account_id}/report/{reference}

Get activity report for the account by specifying the account ID and the reference that is generated by triggering the report. Reports older than a day are deleted when generating a new report.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.report.get

Request

Path Parameters

account_id

Required *

string

ID of the account

reference

Required *

string

Reference for the report to be generated, You can use 'latest' to get the latest report for the given account.

Query Parameters

Response

200 - Successful - report retrieved.

created_by

string

IAMid of the user who triggered the report

reference

string

Unique reference used to generate the report

report_duration

string

Duration in hours for which the report is generated.

report_start_time

string

Start time of the report

report_end_time

string

End time of the report

users

array

List of users

apikeys

array

List of apikeys

serviceids

array

List of serviceids

profiles

array

List of profiles

204 - Report not complete yet.

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Report not found.

500 - Internal Server error. Response if unexpected error situation happened.

Create an IAM access token for a user or service ID using an API key

POST /identity/token#apikey

Creates a non-opaque access token for an API key.

Auditing

Calling this method generates the following auditing event.

• iam-identity.serviceid-apikey.login
• iam-identity.user-apikey.login

Request

Request Body

grant_type

Required *

string

Grant type for this API call. You must set the grant type to `urn:ibm:params:oauth:grant-type:apikey`.

apikey

Required *

string

The value of the api key.

Path Parameters

Query Parameters

Response

200 - Successful operation.

access_token

string

The IAM access token that can be used to invoke various IBM Cloud APIs. Use this token with the prefix Bearer in the HTTP header Authorization for invocations of IAM compatible APIs.

refresh_token

string

(optional) A refresh token that can be used to get a new IAM access token if that token is expired. When using the default client (no basic authorization header) as described in this documentation, this refresh_token cannot be used to retrieve a new IAM access token. When the IAM access token is about to be expired, use the API key to create a new access token.

delegated_refresh_token

string

(optional) A delegated refresh token that can only be consumed by the clients that have been specified in the API call as 'receiver_client_ids'

token_type

string

The type of the token. Currently, only Bearer is returned.

expires_in

integer

Number of seconds until the IAM access token will expire.

expiration

integer

Number of seconds counted since January 1st, 1970, until the IAM access token will expire.

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

context

ExceptionResponseContext

Context fill with key properties for problem determination.

errorCode

string

Error message code of the REST Exception.

errorMessage

string

Error message of the REST Exception. Error messages are derived base on the input locale of the REST request and the available Message catalogs. Dynamic fallback to 'us-english' is happening if no message catalog is available for the provided input locale.

errorDetails

string

Error details of the REST Exception.

requirements

MFARequirementsResponse

Response properties for MFA requirements.

401 - The incoming request did not contain a valid authentication information.

context

ExceptionResponseContext

Context fill with key properties for problem determination.

errorCode

string

Error message code of the REST Exception.

errorMessage

string

Error message of the REST Exception. Error messages are derived base on the input locale of the REST request and the available Message catalogs. Dynamic fallback to 'us-english' is happening if no message catalog is available for the provided input locale.

errorDetails

string

Error details of the REST Exception.

requirements

MFARequirementsResponse

Response properties for MFA requirements.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

context

ExceptionResponseContext

Context fill with key properties for problem determination.

errorCode

string

Error message code of the REST Exception.

errorMessage

string

Error message of the REST Exception. Error messages are derived base on the input locale of the REST request and the available Message catalogs. Dynamic fallback to 'us-english' is happening if no message catalog is available for the provided input locale.

errorDetails

string

Error details of the REST Exception.

requirements

MFARequirementsResponse

Response properties for MFA requirements.

500 - Internal Server error. Response if unexpected error situation happened.

context

ExceptionResponseContext

Context fill with key properties for problem determination.

errorCode

string

Error message code of the REST Exception.

errorMessage

string

Error message of the REST Exception. Error messages are derived base on the input locale of the REST request and the available Message catalogs. Dynamic fallback to 'us-english' is happening if no message catalog is available for the provided input locale.

errorDetails

string

Error details of the REST Exception.

requirements

MFARequirementsResponse

Response properties for MFA requirements.

Create an IAM access token for a user using username / password credentials and an optional account identifier

POST /identity/token#password

Creates a non-opaque access token for a username and password. To be able to call IBM Cloud APIs, the token must be made account-specific. For this purpose, also pass the 32 character long identifier for your account in the API call. This API call is possible only for non-federated IBMid users.

Auditing

Calling this method generates the following auditing event.

• iam-identity.user-password.login

Request

Request Body

grant_type

Required *

string

Grant type for this API call. You must set the grant type to `password`.

username

Required *

string

The value of the username.

password

Required *

string

The value of the password.

account

string

The 32 character identifier of the account. Specify this parameter to get an account-specific IAM token. IBM Cloud APIs require that IAM tokens are account-specific.

Path Parameters

Query Parameters

Response

200 - Successful operation.

access_token

string

The IAM access token that can be used to invoke various IBM Cloud APIs. Use this token with the prefix Bearer in the HTTP header Authorization for invocations of IAM compatible APIs.

refresh_token

string

(optional) A refresh token that can be used to get a new IAM access token if that token is expired. When using the default client (no basic authorization header) as described in this documentation, this refresh_token cannot be used to retrieve a new IAM access token. When the IAM access token is about to be expired, use the API key to create a new access token.

delegated_refresh_token

string

(optional) A delegated refresh token that can only be consumed by the clients that have been specified in the API call as 'receiver_client_ids'

token_type

string

The type of the token. Currently, only Bearer is returned.

expires_in

integer

Number of seconds until the IAM access token will expire.

expiration

integer

Number of seconds counted since January 1st, 1970, until the IAM access token will expire.

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

context

ExceptionResponseContext

Context fill with key properties for problem determination.

errorCode

string

Error message code of the REST Exception.

errorMessage

string

Error message of the REST Exception. Error messages are derived base on the input locale of the REST request and the available Message catalogs. Dynamic fallback to 'us-english' is happening if no message catalog is available for the provided input locale.

errorDetails

string

Error details of the REST Exception.

requirements

MFARequirementsResponse

Response properties for MFA requirements.

401 - The incoming request did not contain valid authentication information.

context

ExceptionResponseContext

Context fill with key properties for problem determination.

errorCode

string

Error message code of the REST Exception.

errorMessage

string

Error message of the REST Exception. Error messages are derived base on the input locale of the REST request and the available Message catalogs. Dynamic fallback to 'us-english' is happening if no message catalog is available for the provided input locale.

errorDetails

string

Error details of the REST Exception.

requirements

MFARequirementsResponse

Response properties for MFA requirements.

403 - The incoming request did not contain valid authentication information.

context

ExceptionResponseContext

Context fill with key properties for problem determination.

errorCode

string

Error message code of the REST Exception.

errorMessage

string

Error message of the REST Exception. Error messages are derived base on the input locale of the REST request and the available Message catalogs. Dynamic fallback to 'us-english' is happening if no message catalog is available for the provided input locale.

errorDetails

string

Error details of the REST Exception.

requirements

MFARequirementsResponse

Response properties for MFA requirements.

500 - Internal server error. Response if unexpected error situation happened.

context

ExceptionResponseContext

Context fill with key properties for problem determination.

errorCode

string

Error message code of the REST Exception.

errorMessage

string

Error message of the REST Exception. Error messages are derived base on the input locale of the REST request and the available Message catalogs. Dynamic fallback to 'us-english' is happening if no message catalog is available for the provided input locale.

errorDetails

string

Error details of the REST Exception.

requirements

MFARequirementsResponse

Response properties for MFA requirements.

Create an IAM access token based on an authorization policy

POST /identity/token#iam-authz

Creates a non-opaque access token, if an appropriate authorization policy is in place. This kind of IAM access token is typically used for access between services.

Request

Request Body

grant_type

Required *

string

Grant type for this API call. You must set the grant type to `urn:ibm:params:oauth:grant-type:iam-authz`.

access_token

Required *

string

The IAM access token of the identity that has the appropriate authorization to create an IAM access token for a given resource.

desired_iam_id

Required *

string

The IAM ID of the IAM access token identity that should be created. The desired_iam_id identifies a resource identity. The IAM ID consists of the prefix crn- and the CRN of the target identity, e.g. crn-crn:v1:bluemix:public:cloud-object-storage:global:a/59bcbfa6ea2f006b4ed7094c1a08dcdd:1a0ec336-f391-4091-a6fb-5e084a4c56f4::.

Response

200 - Successful operation.

access_token

string

The IAM access token that can be used to invoke various IBM Cloud APIs. Use this token with the prefix Bearer in the HTTP header Authorization for invocations of IAM compatible APIs.

refresh_token

string

(optional) A refresh token that can be used to get a new IAM access token if that token is expired. When using the default client (no basic authorization header) as described in this documentation, this refresh_token cannot be used to retrieve a new IAM access token. When the IAM access token is about to be expired, use the API key to create a new access token.

delegated_refresh_token

string

(optional) A delegated refresh token that can only be consumed by the clients that have been specified in the API call as 'receiver_client_ids'

token_type

string

The type of the token. Currently, only Bearer is returned.

expires_in

integer

Number of seconds until the IAM access token will expire.

expiration

integer

Number of seconds counted since January 1st, 1970, until the IAM access token will expire.

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

context

ExceptionResponseContext

Context fill with key properties for problem determination.

errorCode

string

Error message code of the REST Exception.

errorMessage

string

Error message of the REST Exception. Error messages are derived base on the input locale of the REST request and the available Message catalogs. Dynamic fallback to 'us-english' is happening if no message catalog is available for the provided input locale.

errorDetails

string

Error details of the REST Exception.

requirements

MFARequirementsResponse

Response properties for MFA requirements.

401 - The incoming request did not contain a valid authentication information.

context

ExceptionResponseContext

Context fill with key properties for problem determination.

errorCode

string

Error message code of the REST Exception.

errorMessage

string

Error message of the REST Exception. Error messages are derived base on the input locale of the REST request and the available Message catalogs. Dynamic fallback to 'us-english' is happening if no message catalog is available for the provided input locale.

errorDetails

string

Error details of the REST Exception.

requirements

MFARequirementsResponse

Response properties for MFA requirements.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

context

ExceptionResponseContext

Context fill with key properties for problem determination.

errorCode

string

Error message code of the REST Exception.

errorMessage

string

Error message of the REST Exception. Error messages are derived base on the input locale of the REST request and the available Message catalogs. Dynamic fallback to 'us-english' is happening if no message catalog is available for the provided input locale.

errorDetails

string

Error details of the REST Exception.

requirements

MFARequirementsResponse

Response properties for MFA requirements.

500 - Internal Server error. Response if unexpected error situation happened.

context

ExceptionResponseContext

Context fill with key properties for problem determination.

errorCode

string

Error message code of the REST Exception.

errorMessage

string

Error message of the REST Exception. Error messages are derived base on the input locale of the REST request and the available Message catalogs. Dynamic fallback to 'us-english' is happening if no message catalog is available for the provided input locale.

errorDetails

string

Error details of the REST Exception.

requirements

MFARequirementsResponse

Response properties for MFA requirements.

Create an IAM access token and delegated refresh token for a user or service ID

POST /identity/token#apikey-delegated-refresh-token

Creates a non-opaque access token and a delegated refresh token for an API key.

Auditing

Calling this method generates the following auditing event.

• iam-identity.user-apikey.login

Request

Request Body

grant_type

Required *

string

Grant type for this API call. You must set the grant type to `urn:ibm:params:oauth:grant-type:apikey`.

apikey

Required *

string

The value of the API key.

response_type

Required *

string

Either 'delegated_refresh_token' to receive a delegated refresh token only, or 'cloud_iam delegated_refresh_token' to receive both an IAM access token and a delegated refresh token in one API call.

receiver_client_ids

Required *

string

A comma separated list of one or more client IDs that will be able to consume the delegated refresh token. The service that accepts a delegated refresh token as API parameter must expose its client ID to allow this API call. The receiver of the delegated refresh token will be able to use the refresh token until it expires.

delegated_refresh_token_expiry

integer

Expiration in seconds until the delegated refresh token must be consumed by the receiver client IDs. After the expiration, no client ID can consume the delegated refresh token, even if the life time of the refresh token inside is still not expired. The default, if not specified, is 518,400 seconds which corresponds to 6 days.

Path Parameters

Query Parameters

Response

200 - Successful operation.

access_token

string

The IAM access token that can be used to invoke various IBM Cloud APIs. Use this token with the prefix Bearer in the HTTP header Authorization for invocations of IAM compatible APIs.

refresh_token

string

(optional) A refresh token that can be used to get a new IAM access token if that token is expired. When using the default client (no basic authorization header) as described in this documentation, this refresh_token cannot be used to retrieve a new IAM access token. When the IAM access token is about to be expired, use the API key to create a new access token.

delegated_refresh_token

string

(optional) A delegated refresh token that can only be consumed by the clients that have been specified in the API call as 'receiver_client_ids'

token_type

string

The type of the token. Currently, only Bearer is returned.

expires_in

integer

Number of seconds until the IAM access token will expire.

expiration

integer

Number of seconds counted since January 1st, 1970, until the IAM access token will expire.

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

context

ExceptionResponseContext

Context fill with key properties for problem determination.

errorCode

string

Error message code of the REST Exception.

errorMessage

string

Error message of the REST Exception. Error messages are derived base on the input locale of the REST request and the available Message catalogs. Dynamic fallback to 'us-english' is happening if no message catalog is available for the provided input locale.

errorDetails

string

Error details of the REST Exception.

requirements

MFARequirementsResponse

Response properties for MFA requirements.

401 - The incoming request did not contain a valid authentication information.

context

ExceptionResponseContext

Context fill with key properties for problem determination.

errorCode

string

Error message code of the REST Exception.

errorMessage

string

Error message of the REST Exception. Error messages are derived base on the input locale of the REST request and the available Message catalogs. Dynamic fallback to 'us-english' is happening if no message catalog is available for the provided input locale.

errorDetails

string

Error details of the REST Exception.

requirements

MFARequirementsResponse

Response properties for MFA requirements.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

context

ExceptionResponseContext

Context fill with key properties for problem determination.

errorCode

string

Error message code of the REST Exception.

errorMessage

string

Error message of the REST Exception. Error messages are derived base on the input locale of the REST request and the available Message catalogs. Dynamic fallback to 'us-english' is happening if no message catalog is available for the provided input locale.

errorDetails

string

Error details of the REST Exception.

requirements

MFARequirementsResponse

Response properties for MFA requirements.

500 - Internal Server error. Response if unexpected error situation happened.

context

ExceptionResponseContext

Context fill with key properties for problem determination.

errorCode

string

Error message code of the REST Exception.

errorMessage

string

Error message of the REST Exception. Error messages are derived base on the input locale of the REST request and the available Message catalogs. Dynamic fallback to 'us-english' is happening if no message catalog is available for the provided input locale.

errorDetails

string

Error details of the REST Exception.

requirements

MFARequirementsResponse

Response properties for MFA requirements.

Create an IAM access token for a Trusted Profile based on the provided Compute Resource token

POST /identity/token#cr-token

Creates a non-opaque access token without a refresh token for a Trusted Profile

Auditing

Calling this method generates the following auditing event.

• iam-identity.computeresource-token.login

Request

Request Body

grant_type

Required *

string

Grant type for this API call. You must set the grant type to `urn:ibm:params:oauth:grant-type:cr-token`.

cr_token

Required *

string

The value of the Compute Resource token. As this is a JWT token, the string can get very long.

profile_id

string

Pass one of 'profile_id', 'profile_name' or 'profile_crn to select which profile should be used for this IAM token. This call can only succeed if you have also linked the Trusted Profile to the Compute Resource, or you have created a Trust Rule from the Trusted Profile to the Compute Resource. If you pass a 'profile_name', then the profile is looked up based on the account_id of the Compute resource. If you pass a 'profile_id' or 'profile_crn', then the profile must exist in the same account like the Compute Resource.

profile_name

string

see 'profile_id'

profile_crn

string

see 'profile_id'

Path Parameters

Query Parameters

Response

200 - Successful operation.

access_token

string

The IAM access token that can be used to invoke various IBM Cloud APIs. Use this token with the prefix Bearer in the HTTP header Authorization for invocations of IAM compatible APIs.

refresh_token

string

(optional) A refresh token that can be used to get a new IAM access token if that token is expired. When using the default client (no basic authorization header) as described in this documentation, this refresh_token cannot be used to retrieve a new IAM access token. When the IAM access token is about to be expired, use the API key to create a new access token.

delegated_refresh_token

string

(optional) A delegated refresh token that can only be consumed by the clients that have been specified in the API call as 'receiver_client_ids'

token_type

string

The type of the token. Currently, only Bearer is returned.

expires_in

integer

Number of seconds until the IAM access token will expire.

expiration

integer

Number of seconds counted since January 1st, 1970, until the IAM access token will expire.

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

context

ExceptionResponseContext

Context fill with key properties for problem determination.

errorCode

string

Error message code of the REST Exception.

errorMessage

string

Error message of the REST Exception. Error messages are derived base on the input locale of the REST request and the available Message catalogs. Dynamic fallback to 'us-english' is happening if no message catalog is available for the provided input locale.

errorDetails

string

Error details of the REST Exception.

requirements

MFARequirementsResponse

Response properties for MFA requirements.

401 - The incoming request did not contain a valid authentication information.

context

ExceptionResponseContext

Context fill with key properties for problem determination.

errorCode

string

Error message code of the REST Exception.

errorMessage

string

Error message of the REST Exception. Error messages are derived base on the input locale of the REST request and the available Message catalogs. Dynamic fallback to 'us-english' is happening if no message catalog is available for the provided input locale.

errorDetails

string

Error details of the REST Exception.

requirements

MFARequirementsResponse

Response properties for MFA requirements.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

context

ExceptionResponseContext

Context fill with key properties for problem determination.

errorCode

string

Error message code of the REST Exception.

errorMessage

string

Error message of the REST Exception. Error messages are derived base on the input locale of the REST request and the available Message catalogs. Dynamic fallback to 'us-english' is happening if no message catalog is available for the provided input locale.

errorDetails

string

Error details of the REST Exception.

requirements

MFARequirementsResponse

Response properties for MFA requirements.

500 - Internal Server error. Response if unexpected error situation happened.

context

ExceptionResponseContext

Context fill with key properties for problem determination.

errorCode

string

Error message code of the REST Exception.

errorMessage

string

Error message of the REST Exception. Error messages are derived base on the input locale of the REST request and the available Message catalogs. Dynamic fallback to 'us-english' is happening if no message catalog is available for the provided input locale.

errorDetails

string

Error details of the REST Exception.

requirements

MFARequirementsResponse

Response properties for MFA requirements.

Create an IAM access token for a Trusted Profile based on the provided entity. Provided entity can be a identity based token which can be a user token, service id token or a cookie.

POST /identity/token#assume

Creates a non-opaque access token for a profile.

Auditing

Calling this method generates the following auditing event.

• iam-identity.assume-profile.login

Request

Request Body

grant_type

Required *

string

Grant type for this API call. You must set the grant type to `urn:ibm:params:oauth:grant-type:assume`.

access_token

string

Pass one of 'access_token', 'refresh_token' or 'cookie' to get a token for the profile. Provided access_token/refresh_token/iam_cookie need to be generated for the user or service id that has trust relationship with the profile. If the profile being assumed must satisfy an MFA requirement for the account, the access_token/refresh_token (...etc) used to assume the profile must meet the same requirement, using the same level MFA or higher.

refresh_token

string

see 'access_token'

cookie

string

see 'access_token'

profile_id

string

Pass one of 'profile_id', 'profile_crn' or 'profile_name' and 'account' to select which profile should be used for this IAM token. If you pass a 'profile_id' or 'profile_crn', then the profile must exist in the same account. If you pass a 'profile_name' then 'account' need to be passed in the request where the profile is looked up based on the account.

profile_name

string

see 'profile_id'

profile_crn

string

see 'profile_id'

account

string

ID of the account the profile belongs to

Response

200 - Successful operation.

access_token

string

The IAM access token that can be used to invoke various IBM Cloud APIs. Use this token with the prefix Bearer in the HTTP header Authorization for invocations of IAM compatible APIs.

refresh_token

string

(optional) A refresh token that can be used to get a new IAM access token if that token is expired. When using the default client (no basic authorization header) as described in this documentation, this refresh_token cannot be used to retrieve a new IAM access token. When the IAM access token is about to be expired, use the API key to create a new access token.

delegated_refresh_token

string

(optional) A delegated refresh token that can only be consumed by the clients that have been specified in the API call as 'receiver_client_ids'

token_type

string

The type of the token. Currently, only Bearer is returned.

expires_in

integer

Number of seconds until the IAM access token will expire.

expiration

integer

Number of seconds counted since January 1st, 1970, until the IAM access token will expire.

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

context

ExceptionResponseContext

Context fill with key properties for problem determination.

errorCode

string

Error message code of the REST Exception.

errorMessage

string

Error message of the REST Exception. Error messages are derived base on the input locale of the REST request and the available Message catalogs. Dynamic fallback to 'us-english' is happening if no message catalog is available for the provided input locale.

errorDetails

string

Error details of the REST Exception.

requirements

MFARequirementsResponse

Response properties for MFA requirements.

401 - The incoming request did not contain a valid authentication information.

context

ExceptionResponseContext

Context fill with key properties for problem determination.

errorCode

string

Error message code of the REST Exception.

errorMessage

string

Error message of the REST Exception. Error messages are derived base on the input locale of the REST request and the available Message catalogs. Dynamic fallback to 'us-english' is happening if no message catalog is available for the provided input locale.

errorDetails

string

Error details of the REST Exception.

requirements

MFARequirementsResponse

Response properties for MFA requirements.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

context

ExceptionResponseContext

Context fill with key properties for problem determination.

errorCode

string

Error message code of the REST Exception.

errorMessage

string

Error message of the REST Exception. Error messages are derived base on the input locale of the REST request and the available Message catalogs. Dynamic fallback to 'us-english' is happening if no message catalog is available for the provided input locale.

errorDetails

string

Error details of the REST Exception.

requirements

MFARequirementsResponse

Response properties for MFA requirements.

500 - Internal Server error. Response if unexpected error situation happened.

context

ExceptionResponseContext

Context fill with key properties for problem determination.

errorCode

string

Error message code of the REST Exception.

errorMessage

string

Error message of the REST Exception. Error messages are derived base on the input locale of the REST request and the available Message catalogs. Dynamic fallback to 'us-english' is happening if no message catalog is available for the provided input locale.

errorDetails

string

Error details of the REST Exception.

requirements

MFARequirementsResponse

Response properties for MFA requirements.

Get MFA enrollment status for a single user in the account.

GET /v1/mfa/accounts/{account_id}/status

Get MFA enrollment status for a single user in the account.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.mfa-status.get

Request

Path Parameters

account_id

Required *

string

ID of the account

Query Parameters

iam_id

Required *

string

iam_id of the user. This user must be the member of the account.

Response

200 - Successful response. No further actions.

iam_id

string

IAMid of the user

effective_mfa_type

string

currently effective mfa type i.e. id_based_mfa or account_based_mfa

id_based_mfa

IdBasedMfaEnrollment

list of mfa traits associated with the identity

account_based_mfa

AccountBasedMfaEnrollment

list of account based mfa types for the identity

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Report not found.

500 - Internal Server error. Response if unexpected error situation happened.

Trigger MFA enrollment status report for the account

POST /v1/mfa/accounts/{account_id}/report

Trigger MFA enrollment status report for the account by specifying the account ID. It can take a few minutes to generate the report for retrieval.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.report.create

Request

Path Parameters

account_id

Required *

string

ID of the account

Query Parameters

type

string

Optional report type. The supported value is 'mfa_status'. List MFA enrollment status for all the identities.

Response

202 - Create report accepted.

reference

string

Reference for the report to be generated.

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

500 - Internal Server error. Response if unexpected error situation happened.

Get MFA enrollment status report for the account

GET /v1/mfa/accounts/{account_id}/report/{reference}

Get MFA enrollment status report for the account by specifying the account ID and the reference that is generated by triggering the report. Reports older than a day are deleted when generating a new report.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.report.get

Request

Path Parameters

account_id

Required *

string

ID of the account

reference

Required *

string

Reference for the report to be generated, You can use 'latest' to get the latest report for the given account.

Query Parameters

Response

200 - Successful - report retrieved.

created_by

string

IAMid of the user who triggered the report

reference

string

Unique reference used to generate the report

report_time

string

Date time at which report is generated. Date is in ISO format.

account_id

string

BSS account id of the user who triggered the report

ims_account_id

string

IMS account id of the user who triggered the report

users

array

List of users

204 - Report not complete yet.

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Report not found.

500 - Internal Server error. Response if unexpected error situation happened.

List trusted profile templates

GET /v1/profile_templates

List the trusted profile templates in an enterprise account.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile-template.read

Request

Path Parameters

Query Parameters

account_id

string

Account ID of the trusted profile templates to query. This parameter is required unless using a pagetoken.

limit

string

Optional size of a single page.

pagetoken

string

Optional Prev or Next page token returned from a previous query execution. Default is start with first page.

sort

string

Optional sort property. If specified, the returned templates are sorted according to this property.

order

string

Optional sort order.

include_history

string

Defines if the entity history is included in the response.

Response

200 - Successful Template retrieval

context

ResponseContext

Context for problem determination.

offset

integer

The offset of the current page.

limit

integer

Optional size of a single page.

first

string

Link to the first page.

previous

string

Link to the previous available page. If 'previous' property is not part of the response no previous page is available.

next

string

Link to the next available page. If 'next' property is not part of the response no next page is available.

profile_templates

array

List of Profile Templates based on the query paramters and the page size. The profile_templates array is always part of the response but might be empty depending on the query parameter values provided.

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

500 - Internal Server error

Create a trusted profile template

POST /v1/profile_templates

Create a new trusted profile template in an enterprise account.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile-template.create

Request

Request Body

TrustedProfileTemplateRequest

Request to create a trusted profile template.

account_id

string

ID of the account where the template resides.

name

string

The name of the trusted profile template. This is visible only in the enterprise account. Required field when creating a new template. Otherwise this field is optional. If the field is included it will change the name value for all existing versions of the template.

description

string

The description of the trusted profile template. Describe the template for enterprise account users.

profile

TemplateProfileComponentRequest

The trusted profile to be assigned in child accounts.

name

Required *

string

Name of the Profile.

You can use replacement variables in the profile name to adjust the name per account.

The following variables are supported:

• `${template_id}` will be replaced by a unique identifier representing the trusted profile template

• `${template_name}` will be replaced by the current name of the trusted profile template

• `${template_version}` will be replaced by the current version of the trusted profile template

• `${account_id}` will be replaced by the account identifier to which this trusted profile template is assigned to

• `${account_name}` will be replaced by the account name to which this trusted profile template is assigned to

Changes to e.g. the name of the account will NOT cause an update of the trusted profile name. The profile name is processed during account assignment and any template version upgrade, i.e. during that operation, the updated account name would be used.

description

string

Description of the Profile

email

string

Email of the trusted profile

rules

array

Rules for the Profile

identities

array

Identities for the Profile

policy_template_references

array

Existing policy templates that you can reference to assign access in the trusted profile component.

action_controls

ActionControls

Action controls that you can define for identities, rules and policies.

identities

object

rules

Required *

object

policies

Required *

object

Path Parameters

Query Parameters

Response

201 - Template successfully created

id

string

ID of the the template

version

integer

Version of the the template

account_id

string

ID of the account where the template resides.

name

string

The name of the trusted profile template. This is visible only in the enterprise account.

description

string

The description of the trusted profile template. Describe the template for enterprise account users.

committed

boolean

Committed flag determines if the template is ready for assignment

profile

TemplateProfileComponentResponse

The trusted profile to be assigned in child accounts.

policy_template_references

array

Existing policy templates that you can reference to assign access in the trusted profile component.

action_controls

ActionControls

Action control defines adding and removing of identities, rules and policies

history

array

History of the trusted profile template.

entity_tag

string

Entity tag for this templateId-version combination

crn

string

Cloud resource name

created_at

string

Timestamp of when the template was created

created_by_id

string

IAMid of the creator

last_modified_at

string

Timestamp of when the template was last modified

last_modified_by_id

string

IAMid of the identity that made the latest modification

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

500 - Internal Server error

Get latest version of a trusted profile template

GET /v1/profile_templates/{template_id}

Get the latest version of a trusted profile template in an enterprise account.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile-template.read

Request

Path Parameters

template_id

Required *

string

ID of the trusted profile template

Query Parameters

include_history

boolean

Defines if the entity history is included in the response

Response

200 - Successful Template retrieval

id

string

ID of the the template

version

integer

Version of the the template

account_id

string

ID of the account where the template resides.

name

string

The name of the trusted profile template. This is visible only in the enterprise account.

description

string

The description of the trusted profile template. Describe the template for enterprise account users.

committed

boolean

Committed flag determines if the template is ready for assignment

profile

TemplateProfileComponentResponse

The trusted profile to be assigned in child accounts.

policy_template_references

array

Existing policy templates that you can reference to assign access in the trusted profile component.

action_controls

ActionControls

Action control defines adding and removing of identities, rules and policies

history

array

History of the trusted profile template.

entity_tag

string

Entity tag for this templateId-version combination

crn

string

Cloud resource name

created_at

string

Timestamp of when the template was created

created_by_id

string

IAMid of the creator

last_modified_at

string

Timestamp of when the template was last modified

last_modified_by_id

string

IAMid of the identity that made the latest modification

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Template not found.

500 - Internal Server error

Delete all versions of a trusted profile template

DELETE /v1/profile_templates/{template_id}

Delete all versions of a trusted profile template in an enterprise account. If any version is assigned to child accounts, you must first delete the assignment.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile-template.delete

Request

Path Parameters

template_id

Required *

string

ID of the trusted profile template

Query Parameters

Response

204 - Successful Template Deletion

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

500 - Internal Server error

List trusted profile template versions

GET /v1/profile_templates/{template_id}/versions

List the versions of a trusted profile template in an enterprise account.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile-template.read

Request

Path Parameters

template_id

Required *

string

ID of the trusted profile template

Query Parameters

limit

string

Optional size of a single page.

pagetoken

string

Optional Prev or Next page token returned from a previous query execution. Default is start with first page.

sort

string

Optional sort property. If specified, the returned templated are sorted according to this property

order

string

Optional sort order.

include_history

string

Defines if the entity history is included in the response

Response

200 - Successful Template retrieval

context

ResponseContext

Context for problem determination.

offset

integer

The offset of the current page.

limit

integer

Optional size of a single page.

first

string

Link to the first page.

previous

string

Link to the previous available page. If 'previous' property is not part of the response no previous page is available.

next

string

Link to the next available page. If 'next' property is not part of the response no next page is available.

profile_templates

array

List of Profile Templates based on the query paramters and the page size. The profile_templates array is always part of the response but might be empty depending on the query parameter values provided.

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

500 - Internal Server error

Create new version of a trusted profile template

POST /v1/profile_templates/{template_id}/versions

Create a new version of a trusted profile template in an enterprise account.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile-template.create

Request

Request Body

TrustedProfileTemplateRequest

Request to create new version of a Trusted Profile Template

account_id

string

ID of the account where the template resides.

name

string

The name of the trusted profile template. This is visible only in the enterprise account. Required field when creating a new template. Otherwise this field is optional. If the field is included it will change the name value for all existing versions of the template.

description

string

The description of the trusted profile template. Describe the template for enterprise account users.

profile

TemplateProfileComponentRequest

The trusted profile to be assigned in child accounts.

name

Required *

string

Name of the Profile.

You can use replacement variables in the profile name to adjust the name per account.

The following variables are supported:

• `${template_id}` will be replaced by a unique identifier representing the trusted profile template

• `${template_name}` will be replaced by the current name of the trusted profile template

• `${template_version}` will be replaced by the current version of the trusted profile template

• `${account_id}` will be replaced by the account identifier to which this trusted profile template is assigned to

• `${account_name}` will be replaced by the account name to which this trusted profile template is assigned to

Changes to e.g. the name of the account will NOT cause an update of the trusted profile name. The profile name is processed during account assignment and any template version upgrade, i.e. during that operation, the updated account name would be used.

description

string

Description of the Profile

email

string

Email of the trusted profile

rules

array

Rules for the Profile

identities

array

Identities for the Profile

policy_template_references

array

Existing policy templates that you can reference to assign access in the trusted profile component.

action_controls

ActionControls

Action controls that you can define for identities, rules and policies.

identities

object

rules

Required *

object

policies

Required *

object

Path Parameters

template_id

Required *

string

ID of the trusted profile template

Query Parameters

Response

201 - Template version created successfully

id

string

ID of the the template

version

integer

Version of the the template

account_id

string

ID of the account where the template resides.

name

string

The name of the trusted profile template. This is visible only in the enterprise account.

description

string

The description of the trusted profile template. Describe the template for enterprise account users.

committed

boolean

Committed flag determines if the template is ready for assignment

profile

TemplateProfileComponentResponse

The trusted profile to be assigned in child accounts.

policy_template_references

array

Existing policy templates that you can reference to assign access in the trusted profile component.

action_controls

ActionControls

Action control defines adding and removing of identities, rules and policies

history

array

History of the trusted profile template.

entity_tag

string

Entity tag for this templateId-version combination

crn

string

Cloud resource name

created_at

string

Timestamp of when the template was created

created_by_id

string

IAMid of the creator

last_modified_at

string

Timestamp of when the template was last modified

last_modified_by_id

string

IAMid of the identity that made the latest modification

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Template not found

500 - Internal Server error

Get version of trusted profile template

GET /v1/profile_templates/{template_id}/versions/{version}

Get a specific version of a trusted profile template in an enterprise account.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile-template.read

Request

Path Parameters

template_id

Required *

string

ID of the trusted profile template

version

Required *

string

Version of the Profile Template

Query Parameters

include_history

boolean

Defines if the entity history is included in the response

Response

200 - Successful Template retrieval

id

string

ID of the the template

version

integer

Version of the the template

account_id

string

ID of the account where the template resides.

name

string

The name of the trusted profile template. This is visible only in the enterprise account.

description

string

The description of the trusted profile template. Describe the template for enterprise account users.

committed

boolean

Committed flag determines if the template is ready for assignment

profile

TemplateProfileComponentResponse

The trusted profile to be assigned in child accounts.

policy_template_references

array

Existing policy templates that you can reference to assign access in the trusted profile component.

action_controls

ActionControls

Action control defines adding and removing of identities, rules and policies

history

array

History of the trusted profile template.

entity_tag

string

Entity tag for this templateId-version combination

crn

string

Cloud resource name

created_at

string

Timestamp of when the template was created

created_by_id

string

IAMid of the creator

last_modified_at

string

Timestamp of when the template was last modified

last_modified_by_id

string

IAMid of the identity that made the latest modification

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Template version not found.

500 - Internal Server error

Update version of trusted profile template

PUT /v1/profile_templates/{template_id}/versions/{version}

Update a specific version of a trusted profile template in an enterprise account.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile-template.update

Request

Request Body

TrustedProfileTemplateRequest

Request to create a trusted profile template.

account_id

string

ID of the account where the template resides.

name

string

The name of the trusted profile template. This is visible only in the enterprise account. Required field when creating a new template. Otherwise this field is optional. If the field is included it will change the name value for all existing versions of the template.

description

string

The description of the trusted profile template. Describe the template for enterprise account users.

profile

TemplateProfileComponentRequest

The trusted profile to be assigned in child accounts.

name

Required *

string

Name of the Profile.

You can use replacement variables in the profile name to adjust the name per account.

The following variables are supported:

• `${template_id}` will be replaced by a unique identifier representing the trusted profile template

• `${template_name}` will be replaced by the current name of the trusted profile template

• `${template_version}` will be replaced by the current version of the trusted profile template

• `${account_id}` will be replaced by the account identifier to which this trusted profile template is assigned to

• `${account_name}` will be replaced by the account name to which this trusted profile template is assigned to

Changes to e.g. the name of the account will NOT cause an update of the trusted profile name. The profile name is processed during account assignment and any template version upgrade, i.e. during that operation, the updated account name would be used.

description

string

Description of the Profile

email

string

Email of the trusted profile

rules

array

Rules for the Profile

identities

array

Identities for the Profile

policy_template_references

array

Existing policy templates that you can reference to assign access in the trusted profile component.

action_controls

ActionControls

Action controls that you can define for identities, rules and policies.

identities

object

rules

Required *

object

policies

Required *

object

Path Parameters

template_id

Required *

string

ID of the trusted profile template

version

Required *

string

Version of the Profile Template

Query Parameters

Response

200 - Successful updated template

id

string

ID of the the template

version

integer

Version of the the template

account_id

string

ID of the account where the template resides.

name

string

The name of the trusted profile template. This is visible only in the enterprise account.

description

string

The description of the trusted profile template. Describe the template for enterprise account users.

committed

boolean

Committed flag determines if the template is ready for assignment

profile

TemplateProfileComponentResponse

The trusted profile to be assigned in child accounts.

policy_template_references

array

Existing policy templates that you can reference to assign access in the trusted profile component.

action_controls

ActionControls

Action control defines adding and removing of identities, rules and policies

history

array

History of the trusted profile template.

entity_tag

string

Entity tag for this templateId-version combination

crn

string

Cloud resource name

created_at

string

Timestamp of when the template was created

created_by_id

string

IAMid of the creator

last_modified_at

string

Timestamp of when the template was last modified

last_modified_by_id

string

IAMid of the identity that made the latest modification

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Template version not found.

500 - Internal Server error

Delete version of trusted profile template

DELETE /v1/profile_templates/{template_id}/versions/{version}

Delete a specific version of a trusted profile template in an enterprise account. If the version is assigned to child accounts, you must first delete the assignment.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile-template.delete

Request

Path Parameters

template_id

Required *

string

ID of the trusted profile template

version

Required *

string

Version of the Profile Template

Query Parameters

Response

204 - Template Version delete successful

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Template not found

500 - Internal Server error

Commit a template version

POST /v1/profile_templates/{template_id}/versions/{version}/commit

Commit a specific version of a trusted profile template in an enterprise account. You must commit a template before you can assign it to child accounts. Once a template is committed, you can no longer modify the template.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile-template.update

Request

Path Parameters

template_id

Required *

string

ID of the trusted profile template

version

Required *

string

Version of the Profile Template

Query Parameters

Response

204 - Template Version committed

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Template not found

500 - Internal Server error

List account settings templates

GET /v1/account_settings_templates

List account settings templates in an enterprise account

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.account-settings-template.read

Request

Path Parameters

Query Parameters

account_id

string

Account ID of the account settings templates to query. This parameter is required unless using a pagetoken.

limit

string

Optional size of a single page.

pagetoken

string

Optional Prev or Next page token returned from a previous query execution. Default is start with first page.

sort

string

Optional sort property. If specified, the returned templated are sorted according to this property

order

string

Optional sort order.

include_history

string

Defines if the entity history is included in the response

Response

200 - Successful Template retrieval

context

ResponseContext

Context for problem determination.

offset

integer

The offset of the current page.

limit

integer

Optional size of a single page.

first

string

Link to the first page.

previous

string

Link to the previous available page. If 'previous' property is not part of the response no previous page is available.

next

string

Link to the next available page. If 'next' property is not part of the response no next page is available.

account_settings_templates

array

List of account settings templates based on the query paramters and the page size. The account_settings_templates array is always part of the response but might be empty depending on the query parameter values provided.

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

500 - Internal Server error

Create an account settings template

POST /v1/account_settings_templates

Create a new account settings template in an enterprise account.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.account-settings-template.create

Request

Request Body

AccountSettingsTemplateRequest

Request to create an account settings template.

account_id

string

ID of the account where the template resides.

name

string

The name of the trusted profile template. This is visible only in the enterprise account.

description

string

The description of the trusted profile template. Describe the template for enterprise account users.

account_settings

TemplateAccountSettings

IAM account settings to be assigned in child accounts.

restrict_create_service_id

string

Defines whether or not creating the resource is access controlled. Valid values: * RESTRICTED - only users assigned the 'Service ID creator' role on the IAM Identity Service can create service IDs, including the account owner * NOT_RESTRICTED - all members of an account can create service IDs * NOT_SET - to 'unset' a previous set value

restrict_create_platform_apikey

string

Defines whether or not creating the resource is access controlled. Valid values: * RESTRICTED - only users assigned the 'Service ID creator' role on the IAM Identity Service can create service IDs, including the account owner * NOT_RESTRICTED - all members of an account can create service IDs * NOT_SET - to 'unset' a previous set value

allowed_ip_addresses

string

Defines the IP addresses and subnets from which IAM tokens can be created for the account.

mfa

string

MFA trait definitions as follows: * NONE - No MFA trait set * NONE_NO_ROPC- No MFA, disable CLI logins with only a password * TOTP - For all non-federated IBMId users * TOTP4ALL - For all users * LEVEL1 - Email-based MFA for all users * LEVEL2 - TOTP-based MFA for all users * LEVEL3 - Security Key MFA for all users

user_mfa

array

List of users that are exempted from the MFA requirement of the account.

session_expiration_in_seconds

string

Defines the session expiration in seconds for the account. Valid values: * Any whole number between between '900' and '86400' * NOT_SET - To unset account setting and use service default

session_invalidation_in_seconds

string

Defines the period of time in seconds in which a session will be invalidated due to inactivity. Valid values: * Any whole number between '900' and '7200' * NOT_SET - To unset account setting and use service default

max_sessions_per_identity

string

Defines the max allowed sessions per identity required by the account. Valid values: * Any whole number greater than 0 * NOT_SET - To unset account setting and use service default

system_access_token_expiration_in_seconds

string

Defines the access token expiration in seconds. Valid values: * Any whole number between '900' and '3600' * NOT_SET - To unset account setting and use service default

system_refresh_token_expiration_in_seconds

string

Defines the refresh token expiration in seconds. Valid values: * Any whole number between '900' and '259200' * NOT_SET - To unset account setting and use service default

restrict_user_list_visibility

string

Defines whether or not user visibility is access controlled. Valid values: * RESTRICTED - users can view only specific types of users in the account, such as those the user has invited to the account, or descendants of those users based on the classic infrastructure hierarchy * NOT_RESTRICTED - any user in the account can view other users from the Users page in IBM Cloud console * NOT_SET - to 'unset' a previous set value

restrict_user_domains

object

Path Parameters

Query Parameters

Response

201 - Template successfully created

id

string

ID of the the template

version

integer

Version of the the template

account_id

string

ID of the account where the template resides.

name

string

The name of the trusted profile template. This is visible only in the enterprise account.

description

string

The description of the trusted profile template. Describe the template for enterprise account users.

committed

boolean

Committed flag determines if the template is ready for assignment

account_settings

TemplateAccountSettings

IAM account settings to be assigned in child accounts.

history

array

History of the Template.

entity_tag

string

Entity tag for this templateId-version combination

crn

string

Cloud resource name

created_at

string

Template Created At

created_by_id

string

IAMid of the creator

last_modified_at

string

Template last modified at

last_modified_by_id

string

IAMid of the identity that made the latest modification

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

500 - Internal Server error

Get latest version of an account settings template

GET /v1/account_settings_templates/{template_id}

Get the latest version of a specific account settings template in an enterprise account.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.account-settings-template.read

Request

Path Parameters

template_id

Required *

string

ID of the account settings template

Query Parameters

include_history

boolean

Defines if the entity history is included in the response

Response

200 - Successful Template retrieval

id

string

ID of the the template

version

integer

Version of the the template

account_id

string

ID of the account where the template resides.

name

string

The name of the trusted profile template. This is visible only in the enterprise account.

description

string

The description of the trusted profile template. Describe the template for enterprise account users.

committed

boolean

Committed flag determines if the template is ready for assignment

account_settings

TemplateAccountSettings

IAM account settings to be assigned in child accounts.

history

array

History of the Template.

entity_tag

string

Entity tag for this templateId-version combination

crn

string

Cloud resource name

created_at

string

Template Created At

created_by_id

string

IAMid of the creator

last_modified_at

string

Template last modified at

last_modified_by_id

string

IAMid of the identity that made the latest modification

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Template not found.

500 - Internal Server error

Delete all versions of an account settings template

DELETE /v1/account_settings_templates/{template_id}

Delete all versions of an account settings template in an enterprise account. If any version is assigned to child accounts, you must first delete the assignment.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.account-settings-template.delete

Request

Path Parameters

template_id

Required *

string

ID of the account settings template

Query Parameters

Response

204 - Successful Template Deletion

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

500 - Internal Server error

List account settings template versions

GET /v1/account_settings_templates/{template_id}/versions

List the versions of a specific account settings template in an enterprise account.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.account-settings-template.read

Request

Path Parameters

template_id

Required *

string

ID of the account settings template

Query Parameters

limit

string

Optional size of a single page.

pagetoken

string

Optional Prev or Next page token returned from a previous query execution. Default is start with first page.

sort

string

Optional sort property. If specified, the returned templated are sorted according to this property

order

string

Optional sort order.

include_history

string

Defines if the entity history is included in the response

Response

200 - Successful Template retrieval

context

ResponseContext

Context for problem determination.

offset

integer

The offset of the current page.

limit

integer

Optional size of a single page.

first

string

Link to the first page.

previous

string

Link to the previous available page. If 'previous' property is not part of the response no previous page is available.

next

string

Link to the next available page. If 'next' property is not part of the response no next page is available.

account_settings_templates

array

List of account settings templates based on the query paramters and the page size. The account_settings_templates array is always part of the response but might be empty depending on the query parameter values provided.

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

500 - Internal Server error

Create a new version of an account settings template

POST /v1/account_settings_templates/{template_id}/versions

Create a new version of an account settings template in an Enterprise Account

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.account-settings-template.create

Request

Request Body

AccountSettingsTemplateRequest

Request to create new version of an account settings template

account_id

string

ID of the account where the template resides.

name

string

The name of the trusted profile template. This is visible only in the enterprise account.

description

string

The description of the trusted profile template. Describe the template for enterprise account users.

account_settings

TemplateAccountSettings

IAM account settings to be assigned in child accounts.

restrict_create_service_id

string

Defines whether or not creating the resource is access controlled. Valid values: * RESTRICTED - only users assigned the 'Service ID creator' role on the IAM Identity Service can create service IDs, including the account owner * NOT_RESTRICTED - all members of an account can create service IDs * NOT_SET - to 'unset' a previous set value

restrict_create_platform_apikey

string

Defines whether or not creating the resource is access controlled. Valid values: * RESTRICTED - only users assigned the 'Service ID creator' role on the IAM Identity Service can create service IDs, including the account owner * NOT_RESTRICTED - all members of an account can create service IDs * NOT_SET - to 'unset' a previous set value

allowed_ip_addresses

string

Defines the IP addresses and subnets from which IAM tokens can be created for the account.

mfa

string

MFA trait definitions as follows: * NONE - No MFA trait set * NONE_NO_ROPC- No MFA, disable CLI logins with only a password * TOTP - For all non-federated IBMId users * TOTP4ALL - For all users * LEVEL1 - Email-based MFA for all users * LEVEL2 - TOTP-based MFA for all users * LEVEL3 - Security Key MFA for all users

user_mfa

array

List of users that are exempted from the MFA requirement of the account.

session_expiration_in_seconds

string

Defines the session expiration in seconds for the account. Valid values: * Any whole number between between '900' and '86400' * NOT_SET - To unset account setting and use service default

session_invalidation_in_seconds

string

Defines the period of time in seconds in which a session will be invalidated due to inactivity. Valid values: * Any whole number between '900' and '7200' * NOT_SET - To unset account setting and use service default

max_sessions_per_identity

string

Defines the max allowed sessions per identity required by the account. Valid values: * Any whole number greater than 0 * NOT_SET - To unset account setting and use service default

system_access_token_expiration_in_seconds

string

Defines the access token expiration in seconds. Valid values: * Any whole number between '900' and '3600' * NOT_SET - To unset account setting and use service default

system_refresh_token_expiration_in_seconds

string

Defines the refresh token expiration in seconds. Valid values: * Any whole number between '900' and '259200' * NOT_SET - To unset account setting and use service default

restrict_user_list_visibility

string

Defines whether or not user visibility is access controlled. Valid values: * RESTRICTED - users can view only specific types of users in the account, such as those the user has invited to the account, or descendants of those users based on the classic infrastructure hierarchy * NOT_RESTRICTED - any user in the account can view other users from the Users page in IBM Cloud console * NOT_SET - to 'unset' a previous set value

restrict_user_domains

object

Path Parameters

template_id

Required *

string

ID of the account settings template

Query Parameters

Response

201 - Template version created successfully

id

string

ID of the the template

version

integer

Version of the the template

account_id

string

ID of the account where the template resides.

name

string

The name of the trusted profile template. This is visible only in the enterprise account.

description

string

The description of the trusted profile template. Describe the template for enterprise account users.

committed

boolean

Committed flag determines if the template is ready for assignment

account_settings

TemplateAccountSettings

IAM account settings to be assigned in child accounts.

history

array

History of the Template.

entity_tag

string

Entity tag for this templateId-version combination

crn

string

Cloud resource name

created_at

string

Template Created At

created_by_id

string

IAMid of the creator

last_modified_at

string

Template last modified at

last_modified_by_id

string

IAMid of the identity that made the latest modification

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Template not found

500 - Internal Server error

Get version of an account settings template

GET /v1/account_settings_templates/{template_id}/versions/{version}

Get a specific version of an account settings template in an Enterprise Account

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.account-settings-template.read

Request

Path Parameters

template_id

Required *

string

ID of the account settings template

version

Required *

string

Version of the account settings template

Query Parameters

include_history

boolean

Defines if the entity history is included in the response

Response

200 - Successful Template retrieval

id

string

ID of the the template

version

integer

Version of the the template

account_id

string

ID of the account where the template resides.

name

string

The name of the trusted profile template. This is visible only in the enterprise account.

description

string

The description of the trusted profile template. Describe the template for enterprise account users.

committed

boolean

Committed flag determines if the template is ready for assignment

account_settings

TemplateAccountSettings

IAM account settings to be assigned in child accounts.

history

array

History of the Template.

entity_tag

string

Entity tag for this templateId-version combination

crn

string

Cloud resource name

created_at

string

Template Created At

created_by_id

string

IAMid of the creator

last_modified_at

string

Template last modified at

last_modified_by_id

string

IAMid of the identity that made the latest modification

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Template version not found.

500 - Internal Server error

Update version of an account settings template

PUT /v1/account_settings_templates/{template_id}/versions/{version}

Update a specific version of an account settings template in an Enterprise Account

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.account-settings-template.update

Request

Request Body

AccountSettingsTemplateRequest

Request to create an account settings template.

account_id

string

ID of the account where the template resides.

name

string

The name of the trusted profile template. This is visible only in the enterprise account.

description

string

The description of the trusted profile template. Describe the template for enterprise account users.

account_settings

TemplateAccountSettings

IAM account settings to be assigned in child accounts.

restrict_create_service_id

string

Defines whether or not creating the resource is access controlled. Valid values: * RESTRICTED - only users assigned the 'Service ID creator' role on the IAM Identity Service can create service IDs, including the account owner * NOT_RESTRICTED - all members of an account can create service IDs * NOT_SET - to 'unset' a previous set value

restrict_create_platform_apikey

string

Defines whether or not creating the resource is access controlled. Valid values: * RESTRICTED - only users assigned the 'Service ID creator' role on the IAM Identity Service can create service IDs, including the account owner * NOT_RESTRICTED - all members of an account can create service IDs * NOT_SET - to 'unset' a previous set value

allowed_ip_addresses

string

Defines the IP addresses and subnets from which IAM tokens can be created for the account.

mfa

string

MFA trait definitions as follows: * NONE - No MFA trait set * NONE_NO_ROPC- No MFA, disable CLI logins with only a password * TOTP - For all non-federated IBMId users * TOTP4ALL - For all users * LEVEL1 - Email-based MFA for all users * LEVEL2 - TOTP-based MFA for all users * LEVEL3 - Security Key MFA for all users

user_mfa

array

List of users that are exempted from the MFA requirement of the account.

session_expiration_in_seconds

string

Defines the session expiration in seconds for the account. Valid values: * Any whole number between between '900' and '86400' * NOT_SET - To unset account setting and use service default

session_invalidation_in_seconds

string

Defines the period of time in seconds in which a session will be invalidated due to inactivity. Valid values: * Any whole number between '900' and '7200' * NOT_SET - To unset account setting and use service default

max_sessions_per_identity

string

Defines the max allowed sessions per identity required by the account. Valid values: * Any whole number greater than 0 * NOT_SET - To unset account setting and use service default

system_access_token_expiration_in_seconds

string

Defines the access token expiration in seconds. Valid values: * Any whole number between '900' and '3600' * NOT_SET - To unset account setting and use service default

system_refresh_token_expiration_in_seconds

string

Defines the refresh token expiration in seconds. Valid values: * Any whole number between '900' and '259200' * NOT_SET - To unset account setting and use service default

restrict_user_list_visibility

string

Defines whether or not user visibility is access controlled. Valid values: * RESTRICTED - users can view only specific types of users in the account, such as those the user has invited to the account, or descendants of those users based on the classic infrastructure hierarchy * NOT_RESTRICTED - any user in the account can view other users from the Users page in IBM Cloud console * NOT_SET - to 'unset' a previous set value

restrict_user_domains

object

Path Parameters

template_id

Required *

string

ID of the account settings template

version

Required *

string

Version of the account settings template

Query Parameters

Response

200 - Successful updated template

id

string

ID of the the template

version

integer

Version of the the template

account_id

string

ID of the account where the template resides.

name

string

The name of the trusted profile template. This is visible only in the enterprise account.

description

string

The description of the trusted profile template. Describe the template for enterprise account users.

committed

boolean

Committed flag determines if the template is ready for assignment

account_settings

TemplateAccountSettings

IAM account settings to be assigned in child accounts.

history

array

History of the Template.

entity_tag

string

Entity tag for this templateId-version combination

crn

string

Cloud resource name

created_at

string

Template Created At

created_by_id

string

IAMid of the creator

last_modified_at

string

Template last modified at

last_modified_by_id

string

IAMid of the identity that made the latest modification

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Template version not found.

500 - Internal Server error

Delete version of an account settings template

DELETE /v1/account_settings_templates/{template_id}/versions/{version}

Delete a specific version of an account settings template in an Enterprise Account

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.account-settings-template.delete

Request

Path Parameters

template_id

Required *

string

ID of the account settings template

version

Required *

string

Version of the account settings template

Query Parameters

Response

204 - Template Version delete successful

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Template not found

500 - Internal Server error

Commit a template version

POST /v1/account_settings_templates/{template_id}/versions/{version}/commit

Commit a specific version of an account settings template in an Enterprise Account. A Template must be committed before being assigned, and once committed, can no longer be modified.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.account-settings-template.update

Request

Path Parameters

template_id

Required *

string

ID of the account settings template

version

Required *

string

Version of the account settings template

Query Parameters

Response

204 - Template Version committed

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Template not found

500 - Internal Server error

List assignments

GET /v1/account_settings_assignments/

List account settings assignments.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.account-settings-assignment.read

Request

Path Parameters

Query Parameters

account_id

string

Account ID of the Assignments to query. This parameter is required unless using a pagetoken.

template_id

string

Filter results by Template Id

template_version

string

Filter results Template Version

target

string

Filter results by the assignment target

target_type

string

Filter results by the assignment's target type

limit

integer

Optional size of a single page. Default is 20 items per page. Valid range is 1 to 100

pagetoken

string

Optional Prev or Next page token returned from a previous query execution. Default is start with first page.

sort

string

If specified, the items are sorted by the value of this property

order

string

Sort order

include_history

boolean

Defines if the entity history is included in the response

Response

200 - Successful Template retrieval

context

ResponseContext

Context with key properties for problem determination.

offset

integer

The offset of the current page.

limit

integer

Optional size of a single page. Default is 20 items per page. Valid range is 1 to 100

first

string

Link to the first page.

previous

string

Link to the previous available page. If 'previous' property is not part of the response no previous page is available.

next

string

Link to the next available page. If 'next' property is not part of the response no next page is available.

assignments

array

List of Assignments based on the query paramters and the page size. The assignments array is always part of the response but might be empty depending on the query parameter values provided.

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

401 - The incoming request did not contain a valid authentication information.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

500 - Internal Server error

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

Create assignment

POST /v1/account_settings_assignments/

Create an assigment for an account settings template.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.account-settings-assignment.create

Request

Request Body

CreateTemplateAssignmentRequest

Body parameters to create an account settings template Assignment

template_id

Required *

string

ID of the template to assign

template_version

Required *

integer

Version of the template to assign

target_type

Required *

string

Type of target to deploy to

target

Required *

string

Identifier of target to deploy to

Path Parameters

Query Parameters

Response

202 - Successful Assignment Record creation

context

ResponseContext

Context with key properties for problem determination.

id

string

Assignment record Id

account_id

string

Enterprise account Id

template_id

string

Template Id

template_version

integer

Template version

target_type

string

Assignment target type

target

string

Assignment target

status

string

Assignment status

resources

array

Status breakdown per target account of IAM resources created or errors encountered in attempting to create those IAM resources. IAM resources are only included in the response providing the assignment is not in progress. IAM resources are also only included when getting a single assignment, and excluded by list APIs.

history

array

Assignment history

href

string

Href

created_at

string

Assignment created at

created_by_id

string

IAMid of the identity that created the assignment

last_modified_at

string

Assignment modified at

last_modified_by_id

string

IAMid of the identity that last modified the assignment

entity_tag

string

Entity tag for this assignment record

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

401 - The incoming request did not contain a valid authentication information.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

404 - Template not found

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

500 - Internal Server error

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

Get assignment

GET /v1/account_settings_assignments/{assignment_id}

Get an assigment for an account settings template.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.account-settings-assignment.read

Request

Path Parameters

assignment_id

Required *

string

ID of the Assignment Record

Query Parameters

include_history

boolean

Defines if the entity history is included in the response

Response

200 - successful operation

context

ResponseContext

Context with key properties for problem determination.

id

string

Assignment record Id

account_id

string

Enterprise account Id

template_id

string

Template Id

template_version

integer

Template version

target_type

string

Assignment target type

target

string

Assignment target

status

string

Assignment status

resources

array

Status breakdown per target account of IAM resources created or errors encountered in attempting to create those IAM resources. IAM resources are only included in the response providing the assignment is not in progress. IAM resources are also only included when getting a single assignment, and excluded by list APIs.

history

array

Assignment history

href

string

Href

created_at

string

Assignment created at

created_by_id

string

IAMid of the identity that created the assignment

last_modified_at

string

Assignment modified at

last_modified_by_id

string

IAMid of the identity that last modified the assignment

entity_tag

string

Entity tag for this assignment record

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

401 - The incoming request did not contain a valid authentication information.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

404 - Template not found

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

500 - Internal Server error

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

Delete assignment

DELETE /v1/account_settings_assignments/{assignment_id}

Delete an account settings template assignment. This removes any IAM resources created by this assignment in child accounts.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.account-settings-assignment.delete

Request

Path Parameters

assignment_id

Required *

string

ID of the Assignment Record

Query Parameters

Response

202 - Request to delete assignment is accepted

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

401 - The incoming request did not contain a valid authentication information.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

404 - Assignment not found

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

500 - Internal Server error

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

Update assignment

PATCH /v1/account_settings_assignments/{assignment_id}

Update an account settings assignment. Call this method to retry failed assignments or migrate the settings in child accounts to a new version.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.account-settings-assignment.update

Request

Request Body

UpdateTemplateAssignmentRequest

Request to update an assignment

template_version

Required *

integer

Template version to be applied to the assignment. To retry all failed assignments, provide the existing version. To migrate to a different version, provide the new version number.

Path Parameters

assignment_id

Required *

string

ID of the Assignment Record

Query Parameters

Response

200 - successful operation

context

ResponseContext

Context with key properties for problem determination.

id

string

Assignment record Id

account_id

string

Enterprise account Id

template_id

string

Template Id

template_version

integer

Template version

target_type

string

Assignment target type

target

string

Assignment target

status

string

Assignment status

resources

array

Status breakdown per target account of IAM resources created or errors encountered in attempting to create those IAM resources. IAM resources are only included in the response providing the assignment is not in progress. IAM resources are also only included when getting a single assignment, and excluded by list APIs.

history

array

Assignment history

href

string

Href

created_at

string

Assignment created at

created_by_id

string

IAMid of the identity that created the assignment

last_modified_at

string

Assignment modified at

last_modified_by_id

string

IAMid of the identity that last modified the assignment

entity_tag

string

Entity tag for this assignment record

202 - Successful Assignment Record update

context

ResponseContext

Context with key properties for problem determination.

id

string

Assignment record Id

account_id

string

Enterprise account Id

template_id

string

Template Id

template_version

integer

Template version

target_type

string

Assignment target type

target

string

Assignment target

status

string

Assignment status

resources

array

Status breakdown per target account of IAM resources created or errors encountered in attempting to create those IAM resources. IAM resources are only included in the response providing the assignment is not in progress. IAM resources are also only included when getting a single assignment, and excluded by list APIs.

history

array

Assignment history

href

string

Href

created_at

string

Assignment created at

created_by_id

string

IAMid of the identity that created the assignment

last_modified_at

string

Assignment modified at

last_modified_by_id

string

IAMid of the identity that last modified the assignment

entity_tag

string

Entity tag for this assignment record

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

401 - The incoming request did not contain a valid authentication information.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

500 - Internal Server error

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

List assignments

GET /v1/profile_assignments/

List trusted profile template assignments.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile-assignment.read

Request

Path Parameters

Query Parameters

account_id

string

Account ID of the Assignments to query. This parameter is required unless using a pagetoken.

template_id

string

Filter results by Template Id

template_version

string

Filter results Template Version

target

string

Filter results by the assignment target

target_type

string

Filter results by the assignment's target type

limit

integer

Optional size of a single page. Default is 20 items per page. Valid range is 1 to 100

pagetoken

string

Optional Prev or Next page token returned from a previous query execution. Default is start with first page.

sort

string

If specified, the items are sorted by the value of this property

order

string

Sort order

include_history

boolean

Defines if the entity history is included in the response

Response

200 - Successful Template retrieval

context

ResponseContext

Context with key properties for problem determination.

offset

integer

The offset of the current page.

limit

integer

Optional size of a single page. Default is 20 items per page. Valid range is 1 to 100

first

string

Link to the first page.

previous

string

Link to the previous available page. If 'previous' property is not part of the response no previous page is available.

next

string

Link to the next available page. If 'next' property is not part of the response no next page is available.

assignments

array

List of Assignments based on the query paramters and the page size. The assignments array is always part of the response but might be empty depending on the query parameter values provided.

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

401 - The incoming request did not contain a valid authentication information.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

500 - Internal Server error

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

Create assignment

POST /v1/profile_assignments/

Create an assigment for a trusted profile template.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile-assignment.create

Request

Request Body

CreateTemplateAssignmentRequest

Body parameters to create an account settings template Assignment

template_id

Required *

string

ID of the template to assign

template_version

Required *

integer

Version of the template to assign

target_type

Required *

string

Type of target to deploy to

target

Required *

string

Identifier of target to deploy to

Path Parameters

Query Parameters

Response

202 - Successful Assignment Record creation

context

ResponseContext

Context with key properties for problem determination.

id

string

Assignment record Id

account_id

string

Enterprise account Id

template_id

string

Template Id

template_version

integer

Template version

target_type

string

Assignment target type

target

string

Assignment target

status

string

Assignment status

resources

array

Status breakdown per target account of IAM resources created or errors encountered in attempting to create those IAM resources. IAM resources are only included in the response providing the assignment is not in progress. IAM resources are also only included when getting a single assignment, and excluded by list APIs.

history

array

Assignment history

href

string

Href

created_at

string

Assignment created at

created_by_id

string

IAMid of the identity that created the assignment

last_modified_at

string

Assignment modified at

last_modified_by_id

string

IAMid of the identity that last modified the assignment

entity_tag

string

Entity tag for this assignment record

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

401 - The incoming request did not contain a valid authentication information.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

404 - Template not found

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

500 - Internal Server error

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

Get assignment

GET /v1/profile_assignments/{assignment_id}

Get an assigment for a trusted profile template.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile-assignment.read

Request

Path Parameters

assignment_id

Required *

string

ID of the Assignment Record

Query Parameters

include_history

boolean

Defines if the entity history is included in the response

Response

200 - successful operation

context

ResponseContext

Context with key properties for problem determination.

id

string

Assignment record Id

account_id

string

Enterprise account Id

template_id

string

Template Id

template_version

integer

Template version

target_type

string

Assignment target type

target

string

Assignment target

status

string

Assignment status

resources

array

Status breakdown per target account of IAM resources created or errors encountered in attempting to create those IAM resources. IAM resources are only included in the response providing the assignment is not in progress. IAM resources are also only included when getting a single assignment, and excluded by list APIs.

history

array

Assignment history

href

string

Href

created_at

string

Assignment created at

created_by_id

string

IAMid of the identity that created the assignment

last_modified_at

string

Assignment modified at

last_modified_by_id

string

IAMid of the identity that last modified the assignment

entity_tag

string

Entity tag for this assignment record

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

401 - The incoming request did not contain a valid authentication information.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

404 - Template not found

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

500 - Internal Server error

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

Delete assignment

DELETE /v1/profile_assignments/{assignment_id}

Delete a trusted profile assignment. This removes any IAM resources created by this assignment in child accounts.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile-assignment.delete

Request

Path Parameters

assignment_id

Required *

string

ID of the Assignment Record

Query Parameters

Response

202 - Request to delete assignment is accepted

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

401 - The incoming request did not contain a valid authentication information.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

404 - Template not found

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

500 - Internal Server error

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

Update assignment

PATCH /v1/profile_assignments/{assignment_id}

Update a trusted profile assignment. Call this method to retry failed assignments or migrate the trusted profile in child accounts to a new version.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile-assignment.update

Request

Request Body

UpdateTemplateAssignmentRequest

Request to update an assignment

template_version

Required *

integer

Template version to be applied to the assignment. To retry all failed assignments, provide the existing version. To migrate to a different version, provide the new version number.

Path Parameters

assignment_id

Required *

string

ID of the Assignment Record

Query Parameters

Response

200 - successful operation

context

ResponseContext

Context with key properties for problem determination.

id

string

Assignment record Id

account_id

string

Enterprise account Id

template_id

string

Template Id

template_version

integer

Template version

target_type

string

Assignment target type

target

string

Assignment target

status

string

Assignment status

resources

array

Status breakdown per target account of IAM resources created or errors encountered in attempting to create those IAM resources. IAM resources are only included in the response providing the assignment is not in progress. IAM resources are also only included when getting a single assignment, and excluded by list APIs.

history

array

Assignment history

href

string

Href

created_at

string

Assignment created at

created_by_id

string

IAMid of the identity that created the assignment

last_modified_at

string

Assignment modified at

last_modified_by_id

string

IAMid of the identity that last modified the assignment

entity_tag

string

Entity tag for this assignment record

202 - Successful Assignment Record update

context

ResponseContext

Context with key properties for problem determination.

id

string

Assignment record Id

account_id

string

Enterprise account Id

template_id

string

Template Id

template_version

integer

Template version

target_type

string

Assignment target type

target

string

Assignment target

status

string

Assignment status

resources

array

Status breakdown per target account of IAM resources created or errors encountered in attempting to create those IAM resources. IAM resources are only included in the response providing the assignment is not in progress. IAM resources are also only included when getting a single assignment, and excluded by list APIs.

history

array

Assignment history

href

string

Href

created_at

string

Assignment created at

created_by_id

string

IAMid of the identity that created the assignment

last_modified_at

string

Assignment modified at

last_modified_by_id

string

IAMid of the identity that last modified the assignment

entity_tag

string

Entity tag for this assignment record

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

401 - The incoming request did not contain a valid authentication information.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

500 - Internal Server error

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

• console/landing_page

  service: `console`

  preference_id: `landing_page`

  supported identity types: `Trusted Profile`

  type: `string`

  validation: valid path for the IBM Cloud Console (without host part), e.g. `/billing` or `/iam`

• console/global_left_navigation

  service: `console`

  preference_id: `global_left_navigation`

  supported identity types: `Trusted Profile`

  type: `list of strings`

  validation: each entry in the list of strings must match the identifier of one navigation entry in the console; these identifiers are defined and interpreted by the IBM Cloud Console; currently the following entries are supported: `slash,projects,rex,containers,databases,is,logmet,automation,complianceAndSecurity,apis,cp4d,partner-center,sap,satellite,vmWare,watsonx`

Authorization

To call this method for the identity type `Trusted Profile`, you must be assigned one or more IAM access roles that include the following action on the target resource `account` and resource type `preferences`:

• iam-identity.preferences.update

By default, the `Administrator` role on service `iam-identity` contains this action. ">

Update Identity Preference on scope account

PUT /v1/preferences/accounts/{account_id}/identities/{iam_id}/{service}/{preference_id}

Update one Identity Preference on scope `account`.

The following preferences are storing values for identities inside an account, i.e. for each account that an identity is member of, the value stored might be different. This means, users who might be member of multiple accounts can have multiple preferences, one per account. Identities like Service Ids or Trusted Profiles can only exist in one account, therefore they can only have one preference inside their related account.

Preferences

• console/landing_page

  service: `console`

  preference_id: `landing_page`

  supported identity types: `Trusted Profile`

  type: `string`

  validation: valid path for the IBM Cloud Console (without host part), e.g. `/billing` or `/iam`

• console/global_left_navigation

  service: `console`

  preference_id: `global_left_navigation`

  supported identity types: `Trusted Profile`

  type: `list of strings`

  validation: each entry in the list of strings must match the identifier of one navigation entry in the console; these identifiers are defined and interpreted by the IBM Cloud Console; currently the following entries are supported: `slash,projects,rex,containers,databases,is,logmet,automation,complianceAndSecurity,apis,cp4d,partner-center,sap,satellite,vmWare,watsonx`

Authorization

To call this method for the identity type `Trusted Profile`, you must be assigned one or more IAM access roles that include the following action on the target resource `account` and resource type `preferences`:

• iam-identity.preferences.update

By default, the `Administrator` role on service `iam-identity` contains this action.

Auditing

Calling this method generates the following auditing event.

• iam-identity.preferences.update

Request

Request Body

UpdatePreferenceRequest

Request to update one identity preference on scope 'acount'.

value_string

string

contains a string value of the preference. only one value property is set, either 'value_string' or 'value_list_of_strings' is present.

value_list_of_strings

array

contains a list of string values of the preference. only one value property is set, either 'value_string' or 'value_list_of_strings' is present.

Path Parameters

account_id

Required *

string

Account id to update preference for

iam_id

Required *

string

IAM id to update the preference for

service

Required *

string

Service of the preference to be updated

preference_id

Required *

string

Identifier of preference to be updated

Query Parameters

Response

200 - successful operation

service

string

Service of the preference

id

string

Unique ID of the preference

account_id

string

Account ID of the preference, only present for scope 'account'

scope

string

Scope of the preference, 'global' or 'account'

value_string

string

String value of the preference, only one value property is set, either 'value_string' or 'value_list_of_strings' is present.

value_list_of_strings

array

List of values of the preference, only one value property is set, either 'value_string' or 'value_list_of_strings' is present.

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

401 - The incoming request did not contain a valid authentication information.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

404 - preference not found

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

500 - Internal Server error

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

Delete Identity Preference on scope account

DELETE /v1/preferences/accounts/{account_id}/identities/{iam_id}/{service}/{preference_id}

Delete one Identity Preference on scope `account`. For details about the preferences supported and how the method request is authorized, refer to the description of operation `Update Identity Preference on scope account`.

Auditing

Calling this method generates the following auditing event.

• iam-identity.preferences.update

Request

Path Parameters

account_id

Required *

string

Account id to delete preference for

iam_id

Required *

string

IAM id to delete the preference for

service

Required *

string

Service of the preference to be deleted

preference_id

Required *

string

Identifier of preference to be deleted

Query Parameters

Response

204 - Deleted Successful - no further details.

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

401 - The incoming request did not contain a valid authentication information.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

404 - preference not found

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

500 - Internal Server error

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

To call this method for the identity type `Trusted Profile`, one of the following conditions must be true:

• the Authorization token represents the trusted profile which is addressed by this request

• you must be assigned one or more IAM access roles that include the following action on the target resource `account` and resource type `preferences`:

  • iam-identity.preferences.update

  By default, the `Administrator` role on service `iam-identity` contains this action.

• Services inside the IBM Cloud Console can call this method. ">

Get Identity Preference on scope account

GET /v1/preferences/accounts/{account_id}/identities/{iam_id}/{service}/{preference_id}

Get one Identity Preference on scope `account`. For details about the preferences supported, refer to the description of operation `Update Identity Preference on scope account`.

Authorization

To call this method for the identity type `Trusted Profile`, one of the following conditions must be true:

• the Authorization token represents the trusted profile which is addressed by this request

• you must be assigned one or more IAM access roles that include the following action on the target resource `account` and resource type `preferences`:

  • iam-identity.preferences.update

  By default, the `Administrator` role on service `iam-identity` contains this action.

• Services inside the IBM Cloud Console can call this method.

Request

Path Parameters

account_id

Required *

string

Account id to get preference for

iam_id

Required *

string

IAM id to get the preference for

service

Required *

string

Service of the preference to be fetched

preference_id

Required *

string

Identifier of preference to be fetched

Query Parameters

Response

200 - successful operation

service

string

Service of the preference

id

string

Unique ID of the preference

account_id

string

Account ID of the preference, only present for scope 'account'

scope

string

Scope of the preference, 'global' or 'account'

value_string

string

String value of the preference, only one value property is set, either 'value_string' or 'value_list_of_strings' is present.

value_list_of_strings

array

List of values of the preference, only one value property is set, either 'value_string' or 'value_list_of_strings' is present.

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

401 - The incoming request did not contain a valid authentication information.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

404 - preference not found

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

500 - Internal Server error

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

GET /v1/preferences/accounts/{account_id}/identities/{iam_id}

Get all Identity Preferences for one account / identity combination. For details about the preferences supported and how the method request is authorized, refer to the description of operation `Get Identity Preference on scope account`.

If you are not allowed to read a preference, the call will not fail. Instead, this preference is/ these preferences are not returned in the list call.

Request

Path Parameters

account_id

Required *

string

Account id to get preferences for

iam_id

Required *

string

IAM id to get the preferences for

Query Parameters

Response

200 - Successful - Get list of all Identity preferences for one account / user combination

preferences

array

List of Identity Preferences

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

401 - The incoming request did not contain a valid authentication information.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

404 - User iam_id or account_id does not match Authorization token or not found.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

500 - Internal Server error

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

List service ID groups

GET /v1/serviceid_groups

Returns a list of all service ID groups for the given account ID

Request

Path Parameters

Query Parameters

account_id

string

Account ID of the service ID groups to query

Response

200 - Successful response. No further actions.

serviceid_groups

array

List of Service ID groups based on the query parameter

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

401 - The incoming request did not contain a valid authentication information.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

500 - Internal Server error. Response if unexpected error situation happened.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

Create a service ID group

POST /v1/serviceid_groups

Creates a service ID group for the given account ID

Request

Request Body

CreateServiceIdGroupRequest

Request to create a service ID Group.

account_id

Required *

string

ID of the account the service ID group belongs to.

name

Required *

string

Name of the service ID group. Unique in the account.

description

string

Description of the service ID group.

Path Parameters

Query Parameters

Response

201 - Service ID Group successfully created.

id

string

ID of the the service ID group

entity_tag

string

Version of the service ID group details object. You need to specify this value when updating the service ID group to avoid stale updates.

account_id

string

ID of the account the service ID group belongs to.

crn

string

Cloud Resource Name of the item.

name

string

Name of the service ID group. Unique in the account.

description

string

Description of the service ID group.

created_at

string

Timestamp of when the service ID group was created

created_by

string

IAM ID of the user or service which created the Service Id group.

modified_at

string

Timestamp of when the service ID group was modified

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

401 - The incoming request did not contain a valid authentication information.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

500 - Internal Server error

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

Get details of a service ID group

GET /v1/serviceid_groups/{id}

Returns the details of a service ID group.

Request

Path Parameters

id

Required *

string

Unique ID of the service ID group.

Query Parameters

Response

200 - Successful response. No further actions.

id

string

ID of the the service ID group

entity_tag

string

Version of the service ID group details object. You need to specify this value when updating the service ID group to avoid stale updates.

account_id

string

ID of the account the service ID group belongs to.

crn

string

Cloud Resource Name of the item.

name

string

Name of the service ID group. Unique in the account.

description

string

Description of the service ID group.

created_at

string

Timestamp of when the service ID group was created

created_by

string

IAM ID of the user or service which created the Service Id group.

modified_at

string

Timestamp of when the service ID group was modified

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

401 - The incoming request did not contain a valid authentication information.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

404 - The provided service ID group is not found.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

500 - Internal Server error. Response if unexpected error situation happened.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

Update a service ID group

PUT /v1/serviceid_groups/{id}

Update a service ID group

Request

Request Body

UpdateServiceIdGroupRequest

Request to update service ID group.

name

Required *

string

Name of the service ID group. Unique in the account.

description

string

Description of the service ID group.

Path Parameters

id

Required *

string

Unique ID of the service ID group to be updated.

Query Parameters

Response

200 - Successful - Service ID group updated.

id

string

ID of the the service ID group

entity_tag

string

Version of the service ID group details object. You need to specify this value when updating the service ID group to avoid stale updates.

account_id

string

ID of the account the service ID group belongs to.

crn

string

Cloud Resource Name of the item.

name

string

Name of the service ID group. Unique in the account.

description

string

Description of the service ID group.

created_at

string

Timestamp of when the service ID group was created

created_by

string

IAM ID of the user or service which created the Service Id group.

modified_at

string

Timestamp of when the service ID group was modified

400 - Parameter validation failed.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

401 - The incoming request did not contain a valid authentication information.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

404 - The provided service ID group is not found.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

409 - Conflict - there must have been an update in parallel, the specified If-Match header does not match the current service ID group record. Retrieve the current service ID group again and apply the changes to that version.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

500 - Internal Server error. Response if unexpected error situation happened.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

Delete a service ID group

DELETE /v1/serviceid_groups/{id}

Delete a service ID group.

Request

Path Parameters

id

Required *

string

Unique ID of the service ID group.

Query Parameters

Response

204 - Deleted Successful - no further details.

401 - The incoming request did not contain a valid authentication information.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

500 - Internal Server error

context

ResponseContext

Context with key properties for problem determination.

status_code

string

Error message code of the REST Exception.

errors

array

List of errors that occured.

trace

string

Unique ID of the requst.

Get account entity limits

GET /v1/accounts/{account_id}/limits/identity

Returns the details of an account's entity limits with query parameters for consumption details.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.account.get

Request

Path Parameters

account_id

Required *

string

Unique ID of the account.

Query Parameters

serviceid_groups

boolean

Boolean to include serviceid group consumption.

serviceids_per_group

string

Comma seperated list of ServiceID groups to include for consumption.

profiles

string

Boolean to include trusted profiles consumption.

apikeys_per_identity

string

Comma seperated list of IAM IDs to include for API key consumption.

templates

string

Boolean to include template consumption.

template_versions_per_template

string

Comma seperated list of template IDs to include for template version consumption.

idps

string

Boolean to include identity provider consumption.

claim_rules_per_group

string

Comma seperated list of access groups to include for claim rules consumption.

claim_rules_per_profile

string

Comma seperated list of profiles to include for claim rules consumption.

cr_links

string

Boolean to include compute resource links consumption.

cr_links_per_profile

string

Comma seperated list of profile IDs to include for cr links consumption.

cr_rules

string

Boolean to include compute resource rules consumption.

cr_rules_per_profile

string

Comma seperated list of profile IDs to include for cr rules consumption.

Response

200 - Successful response. No further actions.

serviceid_groups

LimitCount

Usage count for service ID groups

serviceids_per_group

object

Usage count for service IDs per group

profiles

LimitCount

Usage count for trusted profiles

apikeys_per_identity

object

Usage count for API keys per identity

profile_templates

LimitCount

Usage count for profile templates

account_settings_templates

LimitCount

Usage count for account settings templates

template_versions_per_template

object

Usage count for template versions per template

idps

LimitCount

Usage count for identity providers

claim_rules_per_group

object

Usage count for claim rules per access group

claim_rules_per_profile

object

Usage count for claim rules per profile

cr_links

LimitCount

Usage count for compute resource links

cr_links_per_profile

object

Usage count for compute resource links per profile

cr_rules

LimitCount

Usage count for compute resource rules

cr_rules_per_profile

object

Usage count for compute resource rules per profile

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

500 - Internal Server error. Response if unexpected error situation happened.

Get account entity limits via POST request

POST /v1/accounts/{account_id}/limits/identity

Returns the details of an account's entity limits using a body for larger list of parameters for consumption details.

Request

Request Body

IdentityLimitsUsageRequest

serviceid_groups

boolean

Flag to include service ID groups usage

serviceids_per_group

array

List of service ID group IDs to get usage for

profiles

boolean

Flag to include trusted profiles usage

apikeys_per_identity

array

List of identity IDs to get API key usage for

templates

boolean

Flag to include templates usage

template_versions_per_template

array

List of template IDs to get version usage for

idps

boolean

Flag to include identity providers usage

claim_rules_per_group

array

List of access group IDs to get claim rules usage for

claim_rules_per_profile

array

List of profile IDs to get claim rules usage for

cr_links

boolean

Flag to include compute resource links usage

cr_links_per_profile

array

List of profile IDs to get compute resource links usage for

cr_rules

boolean

Flag to include compute resource rules usage

cr_rules_per_profile

array

List of profile IDs to get compute resource rules usage for

Path Parameters

account_id

Required *

string

Unique ID of the account.

Query Parameters

Response

200 - Identity limits and usage retrieved successfully.

serviceid_groups

LimitCount

Usage count for service ID groups

serviceids_per_group

object

Usage count for service IDs per group

profiles

LimitCount

Usage count for trusted profiles

apikeys_per_identity

object

Usage count for API keys per identity

profile_templates

LimitCount

Usage count for profile templates

account_settings_templates

LimitCount

Usage count for account settings templates

template_versions_per_template

object

Usage count for template versions per template

idps

LimitCount

Usage count for identity providers

claim_rules_per_group

object

Usage count for claim rules per access group

claim_rules_per_profile

object

Usage count for claim rules per profile

cr_links

LimitCount

Usage count for compute resource links

cr_links_per_profile

object

Usage count for compute resource links per profile

cr_rules

LimitCount

Usage count for compute resource rules

cr_rules_per_profile

object

Usage count for compute resource rules per profile

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

500 - Internal Server error. Response if unexpected error situation happened.

List IdPs

GET /v1/idps/

Request

Path Parameters

Query Parameters

account_id

Required *

string

Account id to query

include_history

string

include history of the idp

Response

200 - Successful response. No further actions.

idps

array

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

500 - Internal Server error. Response if unexpected error situation happened.

Create IdP

POST /v1/idps/

Request

Request Body

CreateIdpRequest

Request to create idp

account_id

Required *

string

Account where the IdP resides in

name

Required *

string

Speaking name of the Identity Provider

type

Required *

string

Type of the IDP

active

boolean

Defines if the IDP is active (enabled) for all accounts (including those who consumed the IdP). Default during creation is true

properties

object

Properties of the IDP. Will be stored plain-text.

idp

object

Identity Provider configuration

sp

object

Service Provider configuration

secrets

object

Secrets of the IDP. Will be stored encrypted.

idp

object

Identity Provider secrets

sp

object

Service Provider secrets (can be left empty to auto-generate SP certs)

share_scope

array

List of targets which can consume the IdP

Path Parameters

Query Parameters

automation

string

boolean to flag if IdP is created via automation

Response

200 - successful operation

idp_id

string

entity_tag

string

account_id

string

name

string

type

string

properties

object

secrets

object

share_scope

array

active

boolean

created_at

string

modified_at

string

201 - Successful response. No further actions.

idp_id

string

entity_tag

string

account_id

string

name

string

type

string

properties

object

secrets

object

share_scope

array

active

boolean

created_at

string

modified_at

string

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

500 - Internal Server error. Response if unexpected error situation happened.

Get IdP

GET /v1/idps/{idp_id}

Request

Path Parameters

idp_id

Required *

string

ID of the IDP

Query Parameters

include_history

string

include history of the idp

Response

200 - Successful response. No further actions.

idp_id

string

entity_tag

string

account_id

string

name

string

type

string

properties

object

secrets

object

share_scope

array

active

boolean

created_at

string

modified_at

string

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Identity Provider with provided ID not found.

500 - Internal Server error. Response if unexpected error situation happened.

Update IdP

PUT /v1/idps/{idp_id}

Request

Request Body

UpdateIdPRequest

Request to update idp

ui_setup_completed

boolean

Defines if the IDP setup was finished in the UI

name

string

Speaking name of the Identity Provider

active

boolean

Defines if the IDP is active (enabled) for all accounts (including those who consumed the IdP)

properties

object

Properties of the IDP. Will be stored plain-text.

idp

object

Identity Provider configuration

sp

object

Service Provider configuration

secrets

object

Secrets of the IDP. Will be stored encrypted.

idp

object

Identity Provider secrets

sp

object

Service Provider secrets

share_scope

array

List of targets which can consume the IdP

Path Parameters

idp_id

Required *

string

ID of the IDP

Query Parameters

force_share_scope_update

boolean

Enforces sharescope update even if active consumers are removed from the share scope

Response

200 - Successful response. No further actions.

idp_id

string

entity_tag

string

account_id

string

name

string

type

string

properties

object

secrets

object

share_scope

array

active

boolean

created_at

string

modified_at

string

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Identity Provider with provided ID not found.

409 - The incoming request is valid but the user is not allowed to perform the requested action.

500 - Internal Server error. Response if unexpected error situation happened.

Delete IdP

DELETE /v1/idps/{idp_id}

Request

Path Parameters

idp_id

Required *

string

ID of the IDP

Query Parameters

Response

200 - Successful response. No further actions.

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Identity Provider with provided ID not found.

500 - Internal Server error. Response if unexpected error situation happened.

Get consumers of IdP

GET /v1/idps/{idp_id}/consumers

Request

Path Parameters

idp_id

Required *

string

ID of the IDP

Query Parameters

Response

200 - Successful response. No further actions.

idp_id

string

consumers

array

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Identity Provider with provided ID not found.

500 - Internal Server error. Response if unexpected error situation happened.

GET /v1/idps/{idp_id}/saml/metadata

Returns the Service Provider (SP) SAML metadata document for the specified Identity Provider.

The generated metadata contains the SP entity ID, signing certificate, supported NameID formats, and Assertion Consumer Service endpoints derived from the Identity Provider configuration.

Request

Path Parameters

idp_id

Required *

string

ID of the IDP

Query Parameters

Response

200 - SAML SP metadata document.

500 - Internal Server error

Import SAML IdP metadata

PUT /v1/idps/{idp_id}/saml/metadata

Import a metadata.xml originating from the federated SAML Identity Provider

Request

Request Body

Path Parameters

idp_id

Required *

string

ID of the IDP

Query Parameters

parse_only

boolean

If true, validates and parses the metadata without updating the Identity Provider.

Response

200 - Successful get

idp_id

string

Realm ID of the Identity Provider.

entity_tag

string

Version information used for optimistic locking.

created_at

string

Creation timestamp.

modified_at

string

Last modification timestamp.

account_id

string

Account that owns the Identity Provider.

name

string

User-friendly name of the Identity Provider.

type

string

properties

object

Type-specific Identity Provider configuration.

secrets

object

Type-specific secret configuration.

history

array

History entries for the Identity Provider.

share_scope

array

Accounts, enterprises, or account groups allowed to consume the IdP.

active

boolean

Indicates whether the Identity Provider is enabled. If disabled, the IdP cannot be used by the owner account or any consumer accounts.

ui_setup_completed

boolean

Internal flag used by the UI to determine whether the Identity Provider should be opened in the setup wizard or the edit dialog.

500 - Internal Server error

Get IdP test results

GET /v1/idps/{idp_id}/test

Get IDP test record.

Request

Path Parameters

idp_id

Required *

string

ID of the IDP

Query Parameters

Response

200 - Successful get

idp_id

string

entity_tag

string

started_at

integer

modified_at

string

idp_version

string

steps

array

404 - Not Found - The requested IdP was not found.

500 - Internal Server error

Trigger IdP configuration test

POST /v1/idps/{idp_id}/test

Request

Path Parameters

idp_id

Required *

string

ID of the IDP

Query Parameters

Response

200 - Test triggered

result

string

test_url

string

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

404 - Identity Provider with provided ID not found.

500 - Internal Server error. Response if unexpected error situation happened.

Get account login settings

GET /v2/loginsettings/{account_id}

Request

Path Parameters

account_id

Required *

string

Account which is bound to the alias

Query Parameters

Response

200 - Successful response. No further actions.

alias

string

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

409 - Create Conflict - API key could not be created. Response if the Object could not be created in the persistence layer.

500 - Internal Server error. Response if unexpected error situation happened.

Update account login settings

PUT /v2/loginsettings/{account_id}

Request

Request Body

UpdateAccountLoginSettings

Request to update

alias

string

Alias of the account

Path Parameters

account_id

Required *

string

Account which is bound to the alias

Query Parameters

Response

200 - Successful response. No further actions.

alias

string

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.

409 - Create Conflict - API key could not be created. Response if the Object could not be created in the persistence layer.

500 - Internal Server error. Response if unexpected error situation happened.

List IdP Settings

GET /v2/loginsettings/{account_id}/idps

Request

Path Parameters

account_id

Required *

string

Account which is bound to the IDP

Query Parameters

type

string

Type of IDP

include_idp_metadata

string

Flag if meta-information about account and idp should be included

Response

200 - Successful response. No further actions.

idps

array

400 - Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.

401 - The incoming request did not contain a valid authentication information.

403 - The incoming request is valid but the user is not allowed to perform the requested action.