IAM Identity Services | IBM Cloud API Docs

Introduction

Last updated: 2023-12-14

The IAM Identity Service API is used to manage service IDs, API key identities, trusted profiles, account security settings and to create IAM access tokens for a user or service ID.

With trusted profile templates and assignments you can centrally manage access for child accounts in your organization from the root enterprise account. Similarly with settings templates and assignments, you can centrally administer account security settings. For more information, see Working with template versions and Best practices for assigning access in an enterprise.

SDKs for Java, Node, Python, and Go are available to make it easier to programmatically access the API from your code. The client libraries that are provided by the SDKs implement best practices for using the API and reduce the amount of code that you need to write. The tab for each language includes code examples that demonstrate how to use the client libraries. For more information about using the SDKs, see the IBM Cloud SDK Common project on GitHub.

The examples that are provided on this page demonstrate how to use IAM Identity Service For more information and detailed examples, check out the IBM Cloud SDK Common project on GitHub.

Installing the Java SDK

Maven

<dependency>
	<groupId>com.ibm.cloud</groupId>
	<artifactId>iam-identity</artifactId>
	<version>{version}</version>
</dependency>
Copy to clipboard

Gradle

compile 'com.ibm.cloud:iam-identity:{version}'

Replace {version} in these examples with the release version.

View on GitHub

https://github.com/IBM/platform-services-java-sdk

Installing the Go SDK

Go modules (recommended): Add the following import in your code, and then run go build or go mod tidy

import (
	"github.com/IBM/platform-services-go-sdk/iamidentityv1"
)

go get -u github.com/IBM/platform-services-go-sdk/iamidentityv1

View on GitHub

https://github.com/IBM/platform-services-go-sdk

Installing the Node SDK

npm install @ibm-cloud/platform-services

View on GitHub

https://github.com/IBM/platform-services-node-sdk

Installing the Python SDK

pip install --upgrade "ibm-platform-services"

View on GitHub

https://github.com/IBM/platform-services-python-sdk

Endpoint URLs

The IAM Identity Services API uses the following public global endpoint URL. When you call the API, add the path for each method to form the complete API endpoint for your requests.

https://iam.cloud.ibm.com

Virtual private cloud (VPC) based access requires a virtual private endpoint gateway (VPE gateway). For more information , see Creating an endpoint gateway.

Private endpoint URL for VPC infrastructure: https://private.iam.cloud.ibm.com. VPE gateway creation is supported in following datacenters:
- Dallas
- Washington
- Frankfurt

If you enabled service endpoints in your account, you can send API requests over the IBM Cloud® private network at the following base endpoint URLs. For more information, see Enabling VRF and service endpoints.

Private endpoint URLs for classic infrastructure. Supported datacenters and urls:
- Dallas: https://private.us-south.iam.cloud.ibm.com
- Washington DC: https://private.us-east.iam.cloud.ibm.com
- Frankfurt DC: https://private.eu-de.iam.cloud.ibm.com

Example API request

curl -u "apikey:{apikey}" -X {request_method} "https://iam.cloud.ibm.com/{method_endpoint}"

Replace {apikey}, {request_method}, and {method_endpoint} in this example with the values for your particular API call.

Authentication

Authorization to the Identity Services REST API is enforced by using an IBM Cloud Identity and Access Management (IAM) access token. The token is used to determine the actions that a user or service ID has access to when they use the API.

You can generate an access token by first creating an API key and then exchanging your API key for an IBM Cloud IAM token.

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

When you use the SDK, configure an IAM authenticator with the IAM API key. The authenticator automatically obtains the IAM access token for the API key and includes it with each request. You can construct an authenticator in either of two ways:

Programmatically by constructing an IAM authenticator instance and supplying your IAM API key
By defining the API key in external configuration properties and then using the SDK authenticator factory to construct an IAM authenticator that uses the configured IAM API key

In this example of using external configuration properties, an IAM authenticator instance is created with the configured API key, and then the service client is constructed with this authenticator instance and the configured service URL.

For more information, see the Authentication section of the IBM Cloud SDK Common documentation.

To call each method, you'll need to be assigned a role that includes the required IAM actions. Each method lists the associated action. For more information about IAM actions and how they map to roles, see IAM Identity service.

You authenticate to the API by using Cloud Identity and Access Management (IAM). You can pass either a bearer token in an authorization header or an API key.

The SDK provides initialization methods for each form of authentication.

Use the API key to have the SDK manage the lifecycle of the access token. The SDK requests an access token, ensures that the access token is valid, includes the access token in each outgoing request, and refreshes it when it expires.
Use the access token to manage the lifecycle yourself. Keep in mind that access tokens are valid for 1 hour, so you must refresh them regularly to maintain access.

For more information, see IAM authentication with the SDK.

To retrieve your access token:

curl -X POST   "https://iam.cloud.ibm.com/identity/token"   --header 'Content-Type: application/x-www-form-urlencoded'   --header 'Accept: application/json'   --data-urlencode 'grant_type=urn:ibm:params:oauth:grant-type:apikey'   --data-urlencode 'apikey=<API_KEY>'
Copy to clipboard

Replace <API_KEY> with your IAM API key.

Setting client options through external configuration

Example environment variables, where <SERVICE_URL> is the endpoint URL and <API_KEY> is your IAM API key

export IAM_IDENTITY_URL=<SERVICE_URL>
export IAM_IDENTITY_AUTHTYPE=iam
export IAM_IDENTITY_APIKEY=<API_KEY>
Copy to clipboard

Example of constructing the service client

import {
    "github.com/IBM/platform-services-go-sdk/iamidentityv1"
}
...
serviceClientOptions := &iamidentityv1.IamIdentityV1Options{}
serviceClient, err := iamidentityv1.NewIamIdentityV1UsingExternalConfig(serviceClientOptions)

Setting client options through external configuration

Example environment variables, where <SERVICE_URL> is the endpoint URL and <API_KEY> is your IAM API key

export IAM_IDENTITY_URL=<SERVICE_URL>
export IAM_IDENTITY_AUTHTYPE=iam
export IAM_IDENTITY_APIKEY=<API_KEY>
Copy to clipboard

Example of constructing the service client

import com.ibm.cloud.platform_services.iam_identity.v1.IamIdentity;
...
IamIdentity serviceClient = IamIdentity.newInstance();
Copy to clipboard

Setting client options through external configuration

Example environment variables, where <SERVICE_URL> is the endpoint URL and <API_KEY> is your IAM API key

export IAM_IDENTITY_URL=<SERVICE_URL>
export IAM_IDENTITY_AUTHTYPE=iam
export IAM_IDENTITY_APIKEY=<API_KEY>
Copy to clipboard

Example of constructing the service client

const IamIdentityV1 = require('@ibm-cloud/platform-services/iam-identity/v1');
...
const serviceClient = IamIdentityV1.newInstance({});
Copy to clipboard

Setting client options through external configuration

Example environment variables, where <SERVICE_URL> is the endpoint URL and <API_KEY> is your IAM API key

export IAM_IDENTITY_URL=<SERVICE_URL>
export IAM_IDENTITY_AUTHTYPE=iam
export IAM_IDENTITY_APIKEY=<API_KEY>
Copy to clipboard

Example of constructing the service client

from ibm_platform_services import IamIdentityV1
...
service_client = IamIdentityV1.new_instance()

Auditing

You can monitor API activity within your account by using the IBM Cloud® Activity Tracker service. You can track when specific API methods are called by reviewing generated events in Activity Tracker.

If an event is tracked for a method, you can find it listed with the method. For more information about how to track IAM activity, see Auditing events for IAM.

Error handling

The IAM Token Service uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response always indicates success. A 400 type response indicates that a parameter validation failed and can occur if required parameters are missing or if any parameter values are invalid. A 401 or 403 response indicates that the incoming request did not contain valid authentication information. A 500 type response indicates an internal server error that is seen in an unexpected error situation.

The Identity Services REST APIs return standard HTTP status codes to indicate the success or failure of a request. The format of the response is represented in JSON as follows:

{
    "trace": "9daee671-916a-4678-850b-10b911f0236d",
    "errors": [
        {
            "code": "invalid_access_token",
            "message": "The provided access token provided is invalid."
        }
    ]
    "status_code": 401
}

If an operation cannot be fulfilled, an appropriate 400 or 500 series HTTP response is returned from the server. The operations that are defined in the Reference section describe example errors that might be returned from a failed request. All responses from the Identity Services REST API are in JSON format.

The following table show the potential error codes the API might return.

HTTP Error Code	Description	Recovery
`200`	Success	The request was successful.
`201`	Created	The resource was successfully created.
`204`	No Content	The request was successful. No response body is provided.
`400`	Bad Request	The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request.
`401`	Unauthorized	You are not authorized to make this request. The token is either missing or expired. Get a new valid token and try again.
`403`	Forbidden	The supplied authentication is not authorized to perform the operation. If this error persists, contact the account owner to check your permissions.
`404`	Not Found	The requested resource can't be found.
`409`	Conflict	The entity is already in the requested state.
`429`	Too Many Requests	Too many requests have been made within a time window. Wait before calling the API again.
`500`	Internal error	Error that is seen in an unexpected error situation.

Additional headers

Some additional headers might be required to make successful requests to the API. Those additional headers are:

An optional transaction ID can be passed to your request, which can be useful for tracking calls through multiple services using one identifier. The header key must be set to Transaction-Id and the value is anything that you choose.

If there is not a transaction ID that is passed in, then one is generated randomly.

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.

GET /v1/apikeys

(iamIdentity *IamIdentityV1) ListAPIKeys(listAPIKeysOptions *ListAPIKeysOptions) (result *APIKeyList, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) ListAPIKeysWithContext(ctx context.Context, listAPIKeysOptions *ListAPIKeysOptions) (result *APIKeyList, response *core.DetailedResponse, err error)

ServiceCall<ApiKeyList> listApiKeys(ListApiKeysOptions listApiKeysOptions)
Copy to clipboard

listApiKeys(params)

list_api_keys(
        self,
        *,
        account_id: Optional[str] = None,
        iam_id: Optional[str] = None,
        pagesize: Optional[int] = None,
        pagetoken: Optional[str] = None,
        scope: Optional[str] = None,
        type: Optional[str] = None,
        sort: Optional[str] = None,
        order: Optional[str] = None,
        include_history: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

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

Request

Instantiate the ListAPIKeysOptions struct and set the fields to provide parameter values for the ListAPIKeys method.

Use the ListApiKeysOptions.Builder to create a ListApiKeysOptions object that contains the parameter values for the listApiKeys method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

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

Allowable values: [entity,account]
Default: entity
type
string
Optional parameter to filter the type of the queried API keys. Can be 'user' or 'serviceid'.

Allowable values: [user,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.

Allowable values: [asc,desc]
Default: asc
include_history
boolean
Defines if the entity history is included in the response.

Default: false

parameter

WithContext method only

ListApiKeysOptions

The ListAPIKeys options.

ListApiKeysOptions

The listApiKeys options.

parameters

accountId
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.
iamId
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
number
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'.

Allowable values: [entity,account]
Default: entity
type
string
Optional parameter to filter the type of the queried API keys. Can be 'user' or 'serviceid'.

Allowable values: [user,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.

Allowable values: [asc,desc]
Default: asc
includeHistory
boolean
Defines if the entity history is included in the response.

Default: false

parameters

account_id
str
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
str
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
int
Optional size of a single page. Default is 20 items per page. Valid range is 1 to 100.
pagetoken
str
Optional Prev or Next page token returned from a previous query execution. Default is start with first page.
scope
str
Optional parameter to define the scope of the queried API keys. Can be 'entity' (default) or 'account'.

Allowable values: [entity,account]
Default: entity
type
str
Optional parameter to filter the type of the queried API keys. Can be 'user' or 'serviceid'.

Allowable values: [user,serviceid]
sort
str
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
str
Optional sort order, valid values are asc and desc. Default: asc.

Allowable values: [asc,desc]
Default: asc
include_history
bool
Defines if the entity history is included in the response.

Default: false

Example request

curl -X GET "https://iam.cloud.ibm.com/v1/apikeys?account_id=ACCOUNT_ID&iam_id=IBMid-123WEREW" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" 
Copy to clipboard

Example request

listAPIKeysOptions := iamIdentityService.NewListAPIKeysOptions()
listAPIKeysOptions.SetAccountID(accountID)
listAPIKeysOptions.SetIamID(iamID)
listAPIKeysOptions.SetIncludeHistory(true)

apiKeyList, response, err := iamIdentityService.ListAPIKeys(listAPIKeysOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(apiKeyList, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

ListApiKeysOptions listApiKeysOptions = new ListApiKeysOptions.Builder()
    .accountId(accountId)
    .iamId(iamId)
    .includeHistory(true)
    .build();

Response<ApiKeyList> response = service.listApiKeys(listApiKeysOptions).execute();
ApiKeyList apiKeyList = response.getResult();

System.out.println(apiKeyList);

Example request

const params = {
  accountId: accountId,
  iamId: iamId,
  includeHistory: true,
};

try {
  const res = await iamIdentityService.listApiKeys(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

api_key_list = iam_identity_service.list_api_keys(
  account_id=account_id, iam_id=iam_id, include_history=True
).get_result()
print(json.dumps(api_key_list, indent=2))
Copy to clipboard

Response

Response Body

ApiKeyList

Response body format for the List API keys V1 REST request.

ApiKeyList

Response body format for the List API keys V1 REST request.

ApiKeyList

Response body format for the List API keys V1 REST request.

ApiKeyList

Response body format for the List API keys V1 REST request.

ApiKeyList

Response body format for the List API keys V1 REST request.

Status Code

200
Successful operation.
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
User iam_id or account_id does not match Authorization token, service ID of the IAM ID not found.
500
Internal Server error.

Example responses

Status 200

{
  "limit": 1,
  "first": "https://iam.cloud.ibm.com/v1/apikeys?pagetoken=PageToken",
  "next": "https://iam.cloud.ibm.com/v1/apikeys?pagetoken=PageToken",
  "apikeys": {
    "id": "ApiKey-fffc06c0-f3fd-49e5-82b5-b9dec9a3c47c",
    "entity_tag": "3-5c26819c7a9df67ac5d51c5761e1ac8a",
    "crn": "crn:v1:bluemix:public:iam-identity::a/100abcde100a41abc100aza678abc0zz::apikey:ApiKey-fffc06c0-f3fd-49e5-82b5-b9dec9a3c47c",
    "locked": false,
    "disabled": false,
    "created_at": "2020-09-28T17:49+0000",
    "created_by": "IBMid-110000AB1Z",
    "modified_at": "2020-09-28T17:49+0000",
    "support_sessions": false,
    "action_when_leaked": "none",
    "name": "apikeyNew",
    "description": "test",
    "iam_id": "IBMid-110000AB1Z",
    "account_id": "100abcde100a41abc100aza678abc0zz"
  }
}
Copy to clipboard

Success example

{
  "limit": 1,
  "first": "https://iam.cloud.ibm.com/v1/apikeys?pagetoken=PageToken",
  "next": "https://iam.cloud.ibm.com/v1/apikeys?pagetoken=PageToken",
  "apikeys": {
    "id": "ApiKey-fffc06c0-f3fd-49e5-82b5-b9dec9a3c47c",
    "entity_tag": "3-5c26819c7a9df67ac5d51c5761e1ac8a",
    "crn": "crn:v1:bluemix:public:iam-identity::a/100abcde100a41abc100aza678abc0zz::apikey:ApiKey-fffc06c0-f3fd-49e5-82b5-b9dec9a3c47c",
    "locked": false,
    "disabled": false,
    "created_at": "2020-09-28T17:49+0000",
    "created_by": "IBMid-110000AB1Z",
    "modified_at": "2020-09-28T17:49+0000",
    "support_sessions": false,
    "action_when_leaked": "none",
    "name": "apikeyNew",
    "description": "test",
    "iam_id": "IBMid-110000AB1Z",
    "account_id": "100abcde100a41abc100aza678abc0zz"
  }
}
Copy to clipboard

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.

POST /v1/apikeys

(iamIdentity *IamIdentityV1) CreateAPIKey(createAPIKeyOptions *CreateAPIKeyOptions) (result *APIKey, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) CreateAPIKeyWithContext(ctx context.Context, createAPIKeyOptions *CreateAPIKeyOptions) (result *APIKey, response *core.DetailedResponse, err error)

ServiceCall<ApiKey> createApiKey(CreateApiKeyOptions createApiKeyOptions)
Copy to clipboard

createApiKey(params)

create_api_key(
        self,
        name: str,
        iam_id: str,
        *,
        description: Optional[str] = None,
        account_id: Optional[str] = None,
        apikey: Optional[str] = None,
        store_value: Optional[bool] = None,
        support_sessions: Optional[bool] = None,
        action_when_leaked: Optional[str] = None,
        entity_lock: Optional[str] = None,
        entity_disable: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.apikey.create

Auditing

Calling this method generates the following auditing events.

Depending on the type of API key that you create, one of the following events is generated.

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

Request

Instantiate the CreateAPIKeyOptions struct and set the fields to provide parameter values for the CreateAPIKey method.

Use the CreateApiKeyOptions.Builder to create a CreateApiKeyOptions object that contains the parameter values for the createApiKey method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.
Entity-Lock
string
Indicates if the API key is locked for further write operations. False by default.

Default: false
Entity-Disable
string
Indicates if the API key is disabled. False by default.

Default: false

Request Body

Required*

CreateApiKeyRequest

Request to create an API key.

parameter

WithContext method only

CreateApiKeyOptions

The CreateAPIKey options.

CreateApiKeyOptions

The createApiKey options.

parameters

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.
iamId
Required*
string
The iam_id that this API key authenticates.
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.
accountId
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.
storeValue
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.
supportSessions
boolean
Defines if the API key supports sessions. Sessions are only supported for user apikeys.
actionWhenLeaked
string
Defines the action to take when API key is leaked, valid values are 'none', 'disable' and 'delete'.
entityLock
string
Indicates if the API key is locked for further write operations. False by default.

Default: false
entityDisable
string
Indicates if the API key is disabled. False by default.

Default: false

parameters

name
Required*
str
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.
iam_id
Required*
str
The iam_id that this API key authenticates.
description
str
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.
account_id
str
The account ID of the API key.
apikey
str
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
bool
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
bool
Defines if the API key supports sessions. Sessions are only supported for user apikeys.
action_when_leaked
str
Defines the action to take when API key is leaked, valid values are 'none', 'disable' and 'delete'.
entity_lock
str
Indicates if the API key is locked for further write operations. False by default.

Default: false
entity_disable
str
Indicates if the API key is disabled. False by default.

Default: false

Example request

curl -X POST "https://iam.cloud.ibm.com/v1/apikeys" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" --data '{
    "name": "My-apikey",
    "description": "my personal key",
    "iam_id": "IBMid-123WEREW",
    "account_id": "ACCOUNT_ID",
    "store_value": false
}'
Copy to clipboard

Example request

createAPIKeyOptions := iamIdentityService.NewCreateAPIKeyOptions(apikeyName, iamID)
createAPIKeyOptions.SetDescription("Example ApiKey")

apiKey, response, err := iamIdentityService.CreateAPIKey(createAPIKeyOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(apiKey, "", "  ")
fmt.Println(string(b))
apikeyID = *apiKey.ID
Copy to clipboard

Example request

CreateApiKeyOptions createApiKeyOptions = new CreateApiKeyOptions.Builder()
    .name(apiKeyName)
    .iamId(iamId)
    .description("Example ApiKey")
    .build();

Response<ApiKey> response = service.createApiKey(createApiKeyOptions).execute();
ApiKey apiKey = response.getResult();
apikeyId = apiKey.getId();

System.out.println(apiKey);

Example request

const params = {
  name: apikeyName,
  iamId: iamId,
  description: 'Example ApiKey',
};

try {
  const res = await iamIdentityService.createApiKey(params);
  apikeyId = res.result.id
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

api_key = iam_identity_service.create_api_key(name=apikey_name, iam_id=iam_id).get_result()
print(json.dumps(api_key, indent=2))

Response

Response Body

ApiKey

Response body format for API key V1 REST requests.

ApiKey

Response body format for API key V1 REST requests.

ApiKey

Response body format for API key V1 REST requests.

ApiKey

Response body format for API key V1 REST requests.

ApiKey

Response body format for API key V1 REST requests.

Status Code

201
API key successfully created. Response if the Object could be created in the persistence layer.
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.

Example responses

Status 201

{
  "id": "ApiKey-5ccff000-9ff1-4481-a760-29c22a7603e7",
  "entity_tag": "1-b4053b5d441613fdad4ff3c28db3e7cc",
  "crn": "crn:v1:bluemix:public:iam-identity::a/100abcde100a41abc100aza678abc0zz::apikey:ApiKey-5ccff000-9ff1-4481-a760-29c22a7603e7",
  "locked": false,
  "disabled": false,
  "created_at": "2020-11-10T12:28+0000",
  "created_by": "IBMid-110000AB1Z",
  "modified_at": "2020-11-10T12:28+0000",
  "support_sessions": false,
  "action_when_leaked": "none",
  "name": "apikey-test",
  "description": "apikey-test",
  "iam_id": "IBMid-110000AB1Z",
  "account_id": "100abcde100a41abc100aza678abc0zz",
  "apikey": "created_apikey"
}
Copy to clipboard

Success example

{
  "id": "ApiKey-5ccff000-9ff1-4481-a760-29c22a7603e7",
  "entity_tag": "1-b4053b5d441613fdad4ff3c28db3e7cc",
  "crn": "crn:v1:bluemix:public:iam-identity::a/100abcde100a41abc100aza678abc0zz::apikey:ApiKey-5ccff000-9ff1-4481-a760-29c22a7603e7",
  "locked": false,
  "disabled": false,
  "created_at": "2020-11-10T12:28+0000",
  "created_by": "IBMid-110000AB1Z",
  "modified_at": "2020-11-10T12:28+0000",
  "support_sessions": false,
  "action_when_leaked": "none",
  "name": "apikey-test",
  "description": "apikey-test",
  "iam_id": "IBMid-110000AB1Z",
  "account_id": "100abcde100a41abc100aza678abc0zz",
  "apikey": "created_apikey"
}
Copy to clipboard

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.

GET /v1/apikeys/details

(iamIdentity *IamIdentityV1) GetAPIKeysDetails(getAPIKeysDetailsOptions *GetAPIKeysDetailsOptions) (result *APIKey, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) GetAPIKeysDetailsWithContext(ctx context.Context, getAPIKeysDetailsOptions *GetAPIKeysDetailsOptions) (result *APIKey, response *core.DetailedResponse, err error)

ServiceCall<ApiKey> getApiKeysDetails(GetApiKeysDetailsOptions getApiKeysDetailsOptions)
Copy to clipboard

getApiKeysDetails(params)

get_api_keys_details(
        self,
        *,
        iam_api_key: Optional[str] = None,
        include_history: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.apikey.get

Request

Instantiate the GetAPIKeysDetailsOptions struct and set the fields to provide parameter values for the GetAPIKeysDetails method.

Use the GetApiKeysDetailsOptions.Builder to create a GetApiKeysDetailsOptions object that contains the parameter values for the getApiKeysDetails method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.
IAM-ApiKey
string
API key value.

Query Parameters

include_history
boolean
Defines if the entity history is included in the response.

Default: false

parameter

WithContext method only

GetApiKeysDetailsOptions

The GetAPIKeysDetails options.

GetApiKeysDetailsOptions

The getApiKeysDetails options.

parameters

iamApiKey
string
API key value.
includeHistory
boolean
Defines if the entity history is included in the response.

Default: false

parameters

iam_api_key
str
API key value.
include_history
bool
Defines if the entity history is included in the response.

Default: false

Example request

curl -X GET "https://iam.cloud.ibm.com/v1/apikeys/details" --header "Authorization: Bearer $TOKEN" --header "IAM-Apikey: APIKEY_VALUE" --header "Content-Type: application/json" 
Copy to clipboard

Example request

getAPIKeysDetailsOptions := iamIdentityService.NewGetAPIKeysDetailsOptions()
getAPIKeysDetailsOptions.SetIamAPIKey(iamAPIKey)
getAPIKeysDetailsOptions.SetIncludeHistory(false)

apiKey, response, err := iamIdentityService.GetAPIKeysDetails(getAPIKeysDetailsOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(apiKey, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

GetApiKeysDetailsOptions getApiKeysDetailsOptions = new GetApiKeysDetailsOptions.Builder()
    .iamApiKey(iamApiKey)
    .includeHistory(false)
    .build();

Response<ApiKey> response = service.getApiKeysDetails(getApiKeysDetailsOptions).execute();
ApiKey apiKey = response.getResult();

System.out.println(apiKey);

Example request

const params = {
  iamApiKey: iamApikey,
  includeHistory: false,
};

try {
  const res = await iamIdentityService.getApiKeysDetails(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

api_key = iam_identity_service.get_api_keys_details(iam_api_key=apikey).get_result()
print(json.dumps(api_key, indent=2))

Response

Response Body

ApiKey

Response body format for API key V1 REST requests.

ApiKey

Response body format for API key V1 REST requests.

ApiKey

Response body format for API key V1 REST requests.

ApiKey

Response body format for API key V1 REST requests.

ApiKey

Response body format for API key V1 REST requests.

Status Code

200
Successful Get of API key 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
API key not found.
500
Internal Server error.

Example responses

Status 200

{
  "id": "ApiKey-5ccff000-9ff1-4481-a760-29c22a7603e7",
  "entity_tag": "1-b4053b5d441613fdad4ff3c28db3e7cc",
  "crn": "crn:v1:bluemix:public:iam-identity::a/100abcde100a41abc100aza678abc0zz::apikey:ApiKey-5ccff000-9ff1-4481-a760-29c22a7603e7",
  "locked": false,
  "disabled": false,
  "created_at": "2020-11-10T12:28+0000",
  "created_by": "IBMid-110000AB1Z",
  "modified_at": "2020-11-10T12:28+0000",
  "support_sessions": false,
  "action_when_leaked": "none",
  "name": "apikey-test",
  "description": "apikey-test",
  "iam_id": "IBMid-110000AB1Z",
  "account_id": "100abcde100a41abc100aza678abc0zz"
}
Copy to clipboard

Success example

{
  "id": "ApiKey-5ccff000-9ff1-4481-a760-29c22a7603e7",
  "entity_tag": "1-b4053b5d441613fdad4ff3c28db3e7cc",
  "crn": "crn:v1:bluemix:public:iam-identity::a/100abcde100a41abc100aza678abc0zz::apikey:ApiKey-5ccff000-9ff1-4481-a760-29c22a7603e7",
  "locked": false,
  "disabled": false,
  "created_at": "2020-11-10T12:28+0000",
  "created_by": "IBMid-110000AB1Z",
  "modified_at": "2020-11-10T12:28+0000",
  "support_sessions": false,
  "action_when_leaked": "none",
  "name": "apikey-test",
  "description": "apikey-test",
  "iam_id": "IBMid-110000AB1Z",
  "account_id": "100abcde100a41abc100aza678abc0zz"
}
Copy to clipboard

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.

GET /v1/apikeys/{id}

(iamIdentity *IamIdentityV1) GetAPIKey(getAPIKeyOptions *GetAPIKeyOptions) (result *APIKey, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) GetAPIKeyWithContext(ctx context.Context, getAPIKeyOptions *GetAPIKeyOptions) (result *APIKey, response *core.DetailedResponse, err error)

ServiceCall<ApiKey> getApiKey(GetApiKeyOptions getApiKeyOptions)
Copy to clipboard

getApiKey(params)

get_api_key(
        self,
        id: str,
        *,
        include_history: Optional[bool] = None,
        include_activity: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.apikey.get

Request

Instantiate the GetAPIKeyOptions struct and set the fields to provide parameter values for the GetAPIKey method.

Use the GetApiKeyOptions.Builder to create a GetApiKeyOptions object that contains the parameter values for the getApiKey method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the 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.

Default: false
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.

Default: false

parameter

WithContext method only

GetApiKeyOptions

The GetAPIKey options.

GetApiKeyOptions

The getApiKey options.

parameters

id
Required*
string
Unique ID of the API key.
includeHistory
boolean
Defines if the entity history is included in the response.

Default: false
includeActivity
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.

Default: false

parameters

id
Required*
str
Unique ID of the API key.
include_history
bool
Defines if the entity history is included in the response.

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

Default: false

Example request

curl -X GET "https://iam.cloud.ibm.com/v1/apikeys/APIKEY_UNIQUE_ID" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" 
Copy to clipboard

Example request

getAPIKeyOptions := iamIdentityService.NewGetAPIKeyOptions(apikeyID)

getAPIKeyOptions.SetIncludeHistory(false)
getAPIKeyOptions.SetIncludeActivity(false)

apiKey, response, err := iamIdentityService.GetAPIKey(getAPIKeyOptions)
if err != nil {
  panic(err)
}
apikeyEtag = response.GetHeaders().Get("Etag")
b, _ := json.MarshalIndent(apiKey, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

GetApiKeyOptions getApiKeyOptions = new GetApiKeyOptions.Builder()
    .id(apikeyId)
    .includeHistory(true)
    .includeActivity(true)
    .build();

Response<ApiKey> response = service.getApiKey(getApiKeyOptions).execute();
ApiKey apiKey = response.getResult();
apikeyEtag = response.getHeaders().values("Etag").get(0);

System.out.println(apiKey);
Copy to clipboard

Example request

const params = {
  id: apikeyId,
  includeActivity: true,
};

try {
  const res = await iamIdentityService.getApiKey(params);
  apikeyEtag = res.headers['etag'];
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

response = iam_identity_service.get_api_key(
  id=apikey_id,
  include_activity=True,
)
api_key = response.get_result()
print(json.dumps(api_key, indent=2))
Copy to clipboard

Response

Response Body

ApiKey

Response body format for API key V1 REST requests.

ApiKey

Response body format for API key V1 REST requests.

ApiKey

Response body format for API key V1 REST requests.

ApiKey

Response body format for API key V1 REST requests.

ApiKey

Response body format for API key V1 REST requests.

Status Code

200
Successful Get of API key.
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.

Example responses

Status 200

{
  "id": "ApiKey-5ccff000-9ff1-4481-a760-29c22a7603e7",
  "entity_tag": "1-b4053b5d441613fdad4ff3c28db3e7cc",
  "crn": "crn:v1:bluemix:public:iam-identity::a/100abcde100a41abc100aza678abc0zz::apikey:ApiKey-5ccff000-9ff1-4481-a760-29c22a7603e7",
  "locked": false,
  "disabled": false,
  "created_at": "2020-11-10T12:28+0000",
  "created_by": "IBMid-110000AB1Z",
  "modified_at": "2020-11-10T12:28+0000",
  "support_sessions": false,
  "action_when_leaked": "none",
  "name": "apikey-test",
  "description": "apikey-test",
  "iam_id": "IBMid-110000AB1Z",
  "account_id": "100abcde100a41abc100aza678abc0zz"
}
Copy to clipboard

Success example

{
  "id": "ApiKey-5ccff000-9ff1-4481-a760-29c22a7603e7",
  "entity_tag": "1-b4053b5d441613fdad4ff3c28db3e7cc",
  "crn": "crn:v1:bluemix:public:iam-identity::a/100abcde100a41abc100aza678abc0zz::apikey:ApiKey-5ccff000-9ff1-4481-a760-29c22a7603e7",
  "locked": false,
  "disabled": false,
  "created_at": "2020-11-10T12:28+0000",
  "created_by": "IBMid-110000AB1Z",
  "modified_at": "2020-11-10T12:28+0000",
  "support_sessions": false,
  "action_when_leaked": "none",
  "name": "apikey-test",
  "description": "apikey-test",
  "iam_id": "IBMid-110000AB1Z",
  "account_id": "100abcde100a41abc100aza678abc0zz"
}
Copy to clipboard

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.

PUT /v1/apikeys/{id}

(iamIdentity *IamIdentityV1) UpdateAPIKey(updateAPIKeyOptions *UpdateAPIKeyOptions) (result *APIKey, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) UpdateAPIKeyWithContext(ctx context.Context, updateAPIKeyOptions *UpdateAPIKeyOptions) (result *APIKey, response *core.DetailedResponse, err error)

ServiceCall<ApiKey> updateApiKey(UpdateApiKeyOptions updateApiKeyOptions)
Copy to clipboard

updateApiKey(params)

update_api_key(
        self,
        id: str,
        if_match: str,
        *,
        name: Optional[str] = None,
        description: Optional[str] = None,
        support_sessions: Optional[bool] = None,
        action_when_leaked: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.apikey.update

Auditing

Calling this method generates the following auditing events.

Depending on the type of API key that you update, one of the following events is generated.

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

Request

Instantiate the UpdateAPIKeyOptions struct and set the fields to provide parameter values for the UpdateAPIKey method.

Use the UpdateApiKeyOptions.Builder to create a UpdateApiKeyOptions object that contains the parameter values for the updateApiKey method.

Custom Headers

If-Match
Required*
string
Version of the API key to be updated. Specify the version that you retrieved when reading the API key. This value helps identifying parallel usage of this API. Pass * to indicate to update any version available. This might result in stale updates.
Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

id
Required*
string
Unique ID of the API key to be updated.

Request Body

Required*

UpdateApiKeyRequest

Request to update an API key.

parameter

WithContext method only

UpdateApiKeyOptions

The UpdateAPIKey options.

UpdateApiKeyOptions

The updateApiKey options.

parameters

id
Required*
string
Unique ID of the API key to be updated.
ifMatch
Required*
string
Version of the API key to be updated. Specify the version that you retrieved when reading the API key. This value helps identifying parallel usage of this API. Pass * to indicate to update any version available. This might result in stale updates.
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.
supportSessions
boolean
Defines if the API key supports sessions. Sessions are only supported for user apikeys.
actionWhenLeaked
string
Defines the action to take when API key is leaked, valid values are 'none', 'disable' and 'delete'.

parameters

id
Required*
str
Unique ID of the API key to be updated.
if_match
Required*
str
Version of the API key to be updated. Specify the version that you retrieved when reading the API key. This value helps identifying parallel usage of this API. Pass * to indicate to update any version available. This might result in stale updates.
name
str
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
str
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
bool
Defines if the API key supports sessions. Sessions are only supported for user apikeys.
action_when_leaked
str
Defines the action to take when API key is leaked, valid values are 'none', 'disable' and 'delete'.

Example request

curl -X PUT "https://iam.cloud.ibm.com/v1/apikeys/APIKEY_UNIQUE_ID" --header "Authorization: Bearer $TOKEN" --header "If-Match: <value of etag header from GET request>" --header "Content-Type: application/json" --data '{
    "name": "My-apikey",
    "description": "my personal key"
}'
Copy to clipboard

Example request

updateAPIKeyOptions := iamIdentityService.NewUpdateAPIKeyOptions(apikeyID, apikeyEtag)
updateAPIKeyOptions.SetDescription("This is an updated description")

apiKey, response, err := iamIdentityService.UpdateAPIKey(updateAPIKeyOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(apiKey, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

UpdateApiKeyOptions updateApiKeyOptions = new UpdateApiKeyOptions.Builder()
    .id(apikeyId)
    .ifMatch(apikeyEtag)
    .description("This is an updated description")
    .build();

Response<ApiKey> response = service.updateApiKey(updateApiKeyOptions).execute();
ApiKey apiKey = response.getResult();

System.out.println(apiKey);

Example request

const params = {
  id: apikeyId,
  ifMatch: apikeyEtag,
  description: 'This is an updated description',
};

try {
  const res = await iamIdentityService.updateApiKey(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

api_key = iam_identity_service.update_api_key(
  id=apikey_id, if_match=apikey_etag, description='This is an updated description'
).get_result()
print(json.dumps(api_key, indent=2))
Copy to clipboard

Response

Response Body

ApiKey

Response body format for API key V1 REST requests.

ApiKey

Response body format for API key V1 REST requests.

ApiKey

Response body format for API key V1 REST requests.

ApiKey

Response body format for API key V1 REST requests.

ApiKey

Response body format for API key V1 REST requests.

Status Code

200
Successful - API key updated.
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.

Example responses

Status 200

{
  "id": "ApiKey-5ccff000-9ff1-4481-a760-29c22a7603e7",
  "entity_tag": "2-cc66d399c705d12b439f1992a465fd5b",
  "crn": "crn:v1:bluemix:public:iam-identity::a/100abcde100a41abc100aza678abc0zz::apikey:ApiKey-5ccff000-9ff1-4481-a760-29c22a7603e7",
  "locked": false,
  "disabled": false,
  "created_at": "2020-11-10T12:28+0000",
  "created_by": "IBMid-110000AB1Z",
  "modified_at": "2020-11-10T13:45+0000",
  "support_sessions": false,
  "action_when_leaked": "none",
  "name": "Apikey-test1",
  "description": "Apikey-test1",
  "iam_id": "IBMid-110000AB1Z",
  "account_id": "100abcde100a41abc100aza678abc0zz"
}
Copy to clipboard

Success example

{
  "id": "ApiKey-5ccff000-9ff1-4481-a760-29c22a7603e7",
  "entity_tag": "2-cc66d399c705d12b439f1992a465fd5b",
  "crn": "crn:v1:bluemix:public:iam-identity::a/100abcde100a41abc100aza678abc0zz::apikey:ApiKey-5ccff000-9ff1-4481-a760-29c22a7603e7",
  "locked": false,
  "disabled": false,
  "created_at": "2020-11-10T12:28+0000",
  "created_by": "IBMid-110000AB1Z",
  "modified_at": "2020-11-10T13:45+0000",
  "support_sessions": false,
  "action_when_leaked": "none",
  "name": "Apikey-test1",
  "description": "Apikey-test1",
  "iam_id": "IBMid-110000AB1Z",
  "account_id": "100abcde100a41abc100aza678abc0zz"
}
Copy to clipboard

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.

DELETE /v1/apikeys/{id}

(iamIdentity *IamIdentityV1) DeleteAPIKey(deleteAPIKeyOptions *DeleteAPIKeyOptions) (response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) DeleteAPIKeyWithContext(ctx context.Context, deleteAPIKeyOptions *DeleteAPIKeyOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> deleteApiKey(DeleteApiKeyOptions deleteApiKeyOptions)
Copy to clipboard

deleteApiKey(params)

delete_api_key(
        self,
        id: str,
        **kwargs,
    ) -> DetailedResponse

Authorization

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

iam-identity.apikey.delete

Auditing

Calling this method generates the following auditing events.

Depending on the type of API key that you delete, one of the following events is generated.

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

Request

Instantiate the DeleteAPIKeyOptions struct and set the fields to provide parameter values for the DeleteAPIKey method.

Use the DeleteApiKeyOptions.Builder to create a DeleteApiKeyOptions object that contains the parameter values for the deleteApiKey method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

id
Required*
string
Unique ID of the API key.

parameter

WithContext method only

DeleteApiKeyOptions

The DeleteAPIKey options.

DeleteApiKeyOptions

The deleteApiKey options.

parameters

id
Required*
string
Unique ID of the API key.

parameters

id
Required*
str
Unique ID of the API key.

Example request

curl -X DELETE "https://iam.cloud.ibm.com/v1/apikeys/APIKEY_UNIQUE_ID" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" 
Copy to clipboard

Example request

deleteAPIKeyOptions := iamIdentityService.NewDeleteAPIKeyOptions(apikeyID)

response, err := iamIdentityService.DeleteAPIKey(deleteAPIKeyOptions)
if err != nil {
  panic(err)
}
Copy to clipboard

Example request

DeleteApiKeyOptions deleteApiKeyOptions = new DeleteApiKeyOptions.Builder()
    .id(apikeyId)
    .build();

Response<Void> response = service.deleteApiKey(deleteApiKeyOptions).execute();

Example request

const params = {
  id: apikeyId,
};

try {
  await iamIdentityService.deleteApiKey(params);
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

response = iam_identity_service.delete_api_key(id=apikey_id)

Response

Status Code

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.

No Sample Response

This method does not specify any sample responses.

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.

POST /v1/apikeys/{id}/lock

(iamIdentity *IamIdentityV1) LockAPIKey(lockAPIKeyOptions *LockAPIKeyOptions) (response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) LockAPIKeyWithContext(ctx context.Context, lockAPIKeyOptions *LockAPIKeyOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> lockApiKey(LockApiKeyOptions lockApiKeyOptions)
Copy to clipboard

lockApiKey(params)

lock_api_key(
        self,
        id: str,
        **kwargs,
    ) -> DetailedResponse

Auditing

Calling this method generates the following auditing events.

Depending on the type of API key that you lock, one of the following events is generated.

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

Request

Instantiate the LockAPIKeyOptions struct and set the fields to provide parameter values for the LockAPIKey method.

Use the LockApiKeyOptions.Builder to create a LockApiKeyOptions object that contains the parameter values for the lockApiKey method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

id
Required*
string
Unique ID of the API key.

parameter

WithContext method only

LockApiKeyOptions

The LockAPIKey options.

LockApiKeyOptions

The lockApiKey options.

parameters

id
Required*
string
Unique ID of the API key.

parameters

id
Required*
str
Unique ID of the API key.

Example request

curl -X POST "https://iam.cloud.ibm.com/v1/apikeys/APIKEY_UNIQUE_ID/lock" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" 
Copy to clipboard

Example request

lockAPIKeyOptions := iamIdentityService.NewLockAPIKeyOptions(apikeyID)

response, err := iamIdentityService.LockAPIKey(lockAPIKeyOptions)
if err != nil {
  panic(err)
}
Copy to clipboard

Example request

LockApiKeyOptions lockApiKeyOptions = new LockApiKeyOptions.Builder()
    .id(apikeyId)
    .build();

Response<Void> response = service.lockApiKey(lockApiKeyOptions).execute();

Example request

const params = {
  id: apikeyId,
};

try {
  await iamIdentityService.lockApiKey(params);
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

response = iam_identity_service.lock_api_key(id=apikey_id)

Response

Status Code

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.

No Sample Response

This method does not specify any sample responses.

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.

DELETE /v1/apikeys/{id}/lock

(iamIdentity *IamIdentityV1) UnlockAPIKey(unlockAPIKeyOptions *UnlockAPIKeyOptions) (response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) UnlockAPIKeyWithContext(ctx context.Context, unlockAPIKeyOptions *UnlockAPIKeyOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> unlockApiKey(UnlockApiKeyOptions unlockApiKeyOptions)
Copy to clipboard

unlockApiKey(params)

unlock_api_key(
        self,
        id: str,
        **kwargs,
    ) -> DetailedResponse

Auditing

Calling this method generates the following auditing events.

Depending on the type of API key that you unlock, one of the following events is generated.

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

Request

Instantiate the UnlockAPIKeyOptions struct and set the fields to provide parameter values for the UnlockAPIKey method.

Use the UnlockApiKeyOptions.Builder to create a UnlockApiKeyOptions object that contains the parameter values for the unlockApiKey method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

id
Required*
string
Unique ID of the API key.

parameter

WithContext method only

UnlockApiKeyOptions

The UnlockAPIKey options.

UnlockApiKeyOptions

The unlockApiKey options.

parameters

id
Required*
string
Unique ID of the API key.

parameters

id
Required*
str
Unique ID of the API key.

Example request

curl -X DELETE "https://iam.cloud.ibm.com/v1/apikeys/APIKEY_UNIQUE_ID/lock" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" 
Copy to clipboard

Example request

unlockAPIKeyOptions := iamIdentityService.NewUnlockAPIKeyOptions(apikeyID)

response, err := iamIdentityService.UnlockAPIKey(unlockAPIKeyOptions)
if err != nil {
  panic(err)
}
Copy to clipboard

Example request

UnlockApiKeyOptions unlockApiKeyOptions = new UnlockApiKeyOptions.Builder()
    .id(apikeyId)
    .build();

Response<Void> response = service.unlockApiKey(unlockApiKeyOptions).execute();

Example request

const params = {
  id: apikeyId,
};

try {
  await iamIdentityService.unlockApiKey(params);
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

response = iam_identity_service.unlock_api_key(id=apikey_id)

Response

Status Code

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.

No Sample Response

This method does not specify any sample responses.

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

POST /v1/apikeys/{id}/disable

(iamIdentity *IamIdentityV1) DisableAPIKey(disableAPIKeyOptions *DisableAPIKeyOptions) (response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) DisableAPIKeyWithContext(ctx context.Context, disableAPIKeyOptions *DisableAPIKeyOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> disableApiKey(DisableApiKeyOptions disableApiKeyOptions)
Copy to clipboard

disableApiKey(params)

disable_api_key(
        self,
        id: str,
        **kwargs,
    ) -> DetailedResponse

Auditing

Calling this method generates the following auditing events.

Depending on the type of API key that you disabled, one of the following events is generated.

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

Request

Instantiate the DisableAPIKeyOptions struct and set the fields to provide parameter values for the DisableAPIKey method.

Use the DisableApiKeyOptions.Builder to create a DisableApiKeyOptions object that contains the parameter values for the disableApiKey method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

id
Required*
string
Unique ID of the API key.

parameter

WithContext method only

DisableApiKeyOptions

The DisableAPIKey options.

DisableApiKeyOptions

The disableApiKey options.

parameters

id
Required*
string
Unique ID of the API key.

parameters

id
Required*
str
Unique ID of the API key.

Example request

curl -X POST "https://iam.cloud.ibm.com/v1/apikeys/APIKEY_UNIQUE_ID/disable" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" 
Copy to clipboard

Example request

disableAPIKeyOptions := iamIdentityService.NewDisableAPIKeyOptions(apikeyID)

response, err := iamIdentityService.DisableAPIKey(disableAPIKeyOptions)
if err != nil {
  panic(err)
}
Copy to clipboard

Example request

DisableApiKeyOptions disableApiKeyOptions = new DisableApiKeyOptions.Builder()
    .id(apikeyId)
    .build();

Response<Void> response = service.disableApiKey(disableApiKeyOptions).execute();

Example request

const params = {
  id: apikeyId,
};

try {
  await iamIdentityService.disableApiKey(params);
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

response = iam_identity_service.disable_api_key(id=apikey_id)

Response

Status Code

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.

No Sample Response

This method does not specify any sample responses.

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

DELETE /v1/apikeys/{id}/disable

(iamIdentity *IamIdentityV1) EnableAPIKey(enableAPIKeyOptions *EnableAPIKeyOptions) (response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) EnableAPIKeyWithContext(ctx context.Context, enableAPIKeyOptions *EnableAPIKeyOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> enableApiKey(EnableApiKeyOptions enableApiKeyOptions)
Copy to clipboard

enableApiKey(params)

enable_api_key(
        self,
        id: str,
        **kwargs,
    ) -> DetailedResponse

Auditing

Calling this method generates the following auditing events.

Depending on the type of API key that you enable, one of the following events is generated.

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

Request

Instantiate the EnableAPIKeyOptions struct and set the fields to provide parameter values for the EnableAPIKey method.

Use the EnableApiKeyOptions.Builder to create a EnableApiKeyOptions object that contains the parameter values for the enableApiKey method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

id
Required*
string
Unique ID of the API key.

parameter

WithContext method only

EnableApiKeyOptions

The EnableAPIKey options.

EnableApiKeyOptions

The enableApiKey options.

parameters

id
Required*
string
Unique ID of the API key.

parameters

id
Required*
str
Unique ID of the API key.

Example request

curl -X DELETE "https://iam.cloud.ibm.com/v1/apikeys/APIKEY_UNIQUE_ID/disable" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" 
Copy to clipboard

Example request

enableAPIKeyOptions := iamIdentityService.NewEnableAPIKeyOptions(apikeyID)

response, err := iamIdentityService.EnableAPIKey(enableAPIKeyOptions)
if err != nil {
  panic(err)
}
Copy to clipboard

Example request

EnableApiKeyOptions enableApiKeyOptions = new EnableApiKeyOptions.Builder()
    .id(apikeyId)
    .build();

Response<Void> response = service.enableApiKey(enableApiKeyOptions).execute();

Example request

const params = {
  id: apikeyId,
};

try {
  await iamIdentityService.enableApiKey(params);
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

response = iam_identity_service.enable_api_key(id=apikey_id)

Response

Status Code

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.

No Sample Response

This method does not specify any sample responses.

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.

GET /v1/serviceids/

(iamIdentity *IamIdentityV1) ListServiceIds(listServiceIdsOptions *ListServiceIdsOptions) (result *ServiceIDList, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) ListServiceIdsWithContext(ctx context.Context, listServiceIdsOptions *ListServiceIdsOptions) (result *ServiceIDList, response *core.DetailedResponse, err error)

ServiceCall<ServiceIdList> listServiceIds(ListServiceIdsOptions listServiceIdsOptions)
Copy to clipboard

listServiceIds(params)

list_service_ids(
        self,
        *,
        account_id: Optional[str] = None,
        name: Optional[str] = None,
        pagesize: Optional[int] = None,
        pagetoken: Optional[str] = None,
        sort: Optional[str] = None,
        order: Optional[str] = None,
        include_history: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Request

Instantiate the ListServiceIdsOptions struct and set the fields to provide parameter values for the ListServiceIds method.

Use the ListServiceIdsOptions.Builder to create a ListServiceIdsOptions object that contains the parameter values for the listServiceIds method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Query Parameters

account_id
string
Account ID of the service ID(s) to query. This parameter is required (unless using a pagetoken).
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.

Allowable values: [asc,desc]
Default: asc
include_history
boolean
Defines if the entity history is included in the response.

Default: false

parameter

WithContext method only

ListServiceIdsOptions

The ListServiceIds options.

ListServiceIdsOptions

The listServiceIds options.

parameters

accountId
string
Account ID of the service ID(s) to query. This parameter is required (unless using a pagetoken).
name
string
Name of the service ID(s) to query. Optional.20 items per page. Valid range is 1 to 100.
pagesize
number
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.

Allowable values: [asc,desc]
Default: asc
includeHistory
boolean
Defines if the entity history is included in the response.

Default: false

parameters

account_id
str
Account ID of the service ID(s) to query. This parameter is required (unless using a pagetoken).
name
str
Name of the service ID(s) to query. Optional.20 items per page. Valid range is 1 to 100.
pagesize
int
Optional size of a single page. Default is 20 items per page. Valid range is 1 to 100.
pagetoken
str
Optional Prev or Next page token returned from a previous query execution. Default is start with first page.
sort
str
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
str
Optional sort order, valid values are asc and desc. Default: asc.

Allowable values: [asc,desc]
Default: asc
include_history
bool
Defines if the entity history is included in the response.

Default: false

Example request

curl -X GET "https://iam.cloud.ibm.com/v1/serviceids?account_id=ACCOUNT_ID&name=My-serviceID" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" 
Copy to clipboard

Example request

listServiceIdsOptions := iamIdentityService.NewListServiceIdsOptions()
listServiceIdsOptions.SetAccountID(accountID)
listServiceIdsOptions.SetName(serviceIDName)

serviceIDList, response, err := iamIdentityService.ListServiceIds(listServiceIdsOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(serviceIDList, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

ListServiceIdsOptions listServiceIdsOptions = new ListServiceIdsOptions.Builder()
    .accountId(accountId)
    .name(serviceIdName)
    .build();

Response<ServiceIdList> response = service.listServiceIds(listServiceIdsOptions).execute();
ServiceIdList serviceIdList = response.getResult();

System.out.println(serviceIdList);

Example request

const params = {
  accountId: accountId,
  name: serviceIdName,
};

try {
  const res = await iamIdentityService.listServiceIds(params)
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

service_id_list = iam_identity_service.list_service_ids(
  account_id=account_id, name=serviceid_name
).get_result()
print(json.dumps(service_id_list, indent=2))

Response

Response Body

ServiceIdList

Response body format for the list service ID V1 REST request.

ServiceIdList

Response body format for the list service ID V1 REST request.

ServiceIdList

Response body format for the list service ID V1 REST request.

ServiceIdList

Response body format for the list service ID V1 REST request.

ServiceIdList

Response body format for the list service ID V1 REST request.

Status Code

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.
500
Internal Server error. Response if unexpected error situation happened.

Example responses

Status 200

{
  "offset": 0,
  "limit": 1,
  "first": "https://iam.cloud.ibm.com/v1/serviceids?account_id=accountId",
  "next": "https://iam.cloud.ibm.com/v1/serviceids?pagetoken=pageToken",
  "serviceids": {
    "id": "ServiceId-ee1103f8-e03b-4d02-a977-e540ebdffb16",
    "iam_id": "iam-ServiceId-ee1103f8-e03b-4d02-a977-e540ebdffb16",
    "entity_tag": "3-c46d2fd21b701adf7eb67cfd1a498fde",
    "crn": "crn:v1:bluemix:public:iam-identity::a/100abcde100a41abc100aza678abc0zz::serviceid:ServiceId-ee1103f8-e03b-4d02-a977-e540ebdffb16",
    "locked": false,
    "created_at": "2020-10-16T10:36+0000",
    "modified_at": "2020-10-16T10:36+0000",
    "account_id": "100abcde100a41abc100aza678abc0zz",
    "name": "serviceId-test",
    "description": "serviceId-test",
    "unique_instance_crns": []
  }
}
Copy to clipboard

Success example

{
  "offset": 0,
  "limit": 1,
  "first": "https://iam.cloud.ibm.com/v1/serviceids?account_id=accountId",
  "next": "https://iam.cloud.ibm.com/v1/serviceids?pagetoken=pageToken",
  "serviceids": {
    "id": "ServiceId-ee1103f8-e03b-4d02-a977-e540ebdffb16",
    "iam_id": "iam-ServiceId-ee1103f8-e03b-4d02-a977-e540ebdffb16",
    "entity_tag": "3-c46d2fd21b701adf7eb67cfd1a498fde",
    "crn": "crn:v1:bluemix:public:iam-identity::a/100abcde100a41abc100aza678abc0zz::serviceid:ServiceId-ee1103f8-e03b-4d02-a977-e540ebdffb16",
    "locked": false,
    "created_at": "2020-10-16T10:36+0000",
    "modified_at": "2020-10-16T10:36+0000",
    "account_id": "100abcde100a41abc100aza678abc0zz",
    "name": "serviceId-test",
    "description": "serviceId-test",
    "unique_instance_crns": []
  }
}
Copy to clipboard

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.

POST /v1/serviceids/

(iamIdentity *IamIdentityV1) CreateServiceID(createServiceIDOptions *CreateServiceIDOptions) (result *ServiceID, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) CreateServiceIDWithContext(ctx context.Context, createServiceIDOptions *CreateServiceIDOptions) (result *ServiceID, response *core.DetailedResponse, err error)

ServiceCall<ServiceId> createServiceId(CreateServiceIdOptions createServiceIdOptions)
Copy to clipboard

createServiceId(params)

create_service_id(
        self,
        account_id: str,
        name: str,
        *,
        description: Optional[str] = None,
        unique_instance_crns: Optional[List[str]] = None,
        apikey: Optional['ApiKeyInsideCreateServiceIdRequest'] = None,
        entity_lock: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.serviceid.create

Auditing

Calling this method generates the following auditing event.

iam-identity.account-serviceid.create

Request

Instantiate the CreateServiceIDOptions struct and set the fields to provide parameter values for the CreateServiceID method.

Use the CreateServiceIdOptions.Builder to create a CreateServiceIdOptions object that contains the parameter values for the createServiceId method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.
Entity-Lock
string
Indicates if the service ID is locked for further write operations. False by default.

Default: false

Request Body

Required*

CreateServiceIdRequest

Request to create a service ID.

parameter

WithContext method only

CreateServiceIdOptions

The CreateServiceID options.

CreateServiceIdOptions

The createServiceId options.

parameters

accountId
Required*
string
ID of the account the service ID belongs to.
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.
uniqueInstanceCrns
string[]
Optional list of CRNs (string array) which point to the services connected to the service ID.
apikey
Parameters for the API key in the Create service Id V1 REST request.
entityLock
string
Indicates if the service ID is locked for further write operations. False by default.

Default: false

parameters

account_id
Required*
str
ID of the account the service ID belongs to.
name
Required*
str
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
str
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
List[str]
Optional list of CRNs (string array) which point to the services connected to the service ID.
apikey
Parameters for the API key in the Create service Id V1 REST request.
entity_lock
str
Indicates if the service ID is locked for further write operations. False by default.

Default: false

Example request

curl -X POST "https://iam.cloud.ibm.com/v1/serviceids" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" --data '{
    "name": "My-serviceID",
    "description": "my special service ID",
    "account_id": "ACCOUNT_ID"
}'
Copy to clipboard

Example request

createServiceIDOptions := iamIdentityService.NewCreateServiceIDOptions(accountID, serviceIDName)
createServiceIDOptions.SetDescription("Example ServiceId")

serviceID, response, err := iamIdentityService.CreateServiceID(createServiceIDOptions)
if err != nil {
  panic(err)
}
svcID = *serviceID.ID
b, _ := json.MarshalIndent(serviceID, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

CreateServiceIdOptions createServiceIdOptions = new CreateServiceIdOptions.Builder()
    .accountId(accountId)
    .name(serviceIdName)
    .description("Example ServiceId")
    .build();

Response<ServiceId> response = service.createServiceId(createServiceIdOptions).execute();
ServiceId serviceId = response.getResult();
svcId = serviceId.getId();

System.out.println(serviceId);

Example request

const params = {
  accountId: accountId,
  name: serviceIdName,
  description: 'Example ServiceId',
};

try {
  const res = await iamIdentityService.createServiceId(params);
  svcId = res.result.id;
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

service_id = iam_identity_service.create_service_id(
  account_id=account_id, name=serviceid_name, description='Example ServiceId'
).get_result()
print(json.dumps(service_id, indent=2))
Copy to clipboard

Response

Response Body

ServiceId

Response body format for service ID V1 REST requests.

ServiceId

Response body format for service ID V1 REST requests.

ServiceId

Response body format for service ID V1 REST requests.

ServiceId

Response body format for service ID V1 REST requests.

ServiceId

Response body format for service ID V1 REST requests.

Status Code

201
Service ID successfully created.
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.

Example responses

Status 201

{
  "id": "ServiceId-cb36c9a9-778f-4985-a398-dbec6523054a",
  "iam_id": "iam-ServiceId-cb36c9a9-778f-4985-a398-dbec6523054a",
  "entity_tag": "1-b5edc4362f94fb1fa5f009467b1db039",
  "crn": "crn:v1:bluemix:public:iam-identity::a/100abcde100a41abc100aza678abc0zz::serviceid:ServiceId-cb36c9a9-778f-4985-a398-dbec6523054a",
  "locked": false,
  "created_at": "2020-11-10T14:05+0000",
  "modified_at": "2020-11-10T14:05+0000",
  "account_id": "100abcde100a41abc100aza678abc0zz",
  "name": "New-serviceID",
  "description": "New-serviceID-desc",
  "unique_instance_crns": []
}
Copy to clipboard

Success example

{
  "id": "ServiceId-cb36c9a9-778f-4985-a398-dbec6523054a",
  "iam_id": "iam-ServiceId-cb36c9a9-778f-4985-a398-dbec6523054a",
  "entity_tag": "1-b5edc4362f94fb1fa5f009467b1db039",
  "crn": "crn:v1:bluemix:public:iam-identity::a/100abcde100a41abc100aza678abc0zz::serviceid:ServiceId-cb36c9a9-778f-4985-a398-dbec6523054a",
  "locked": false,
  "created_at": "2020-11-10T14:05+0000",
  "modified_at": "2020-11-10T14:05+0000",
  "account_id": "100abcde100a41abc100aza678abc0zz",
  "name": "New-serviceID",
  "description": "New-serviceID-desc",
  "unique_instance_crns": []
}
Copy to clipboard

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.

GET /v1/serviceids/{id}

(iamIdentity *IamIdentityV1) GetServiceID(getServiceIDOptions *GetServiceIDOptions) (result *ServiceID, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) GetServiceIDWithContext(ctx context.Context, getServiceIDOptions *GetServiceIDOptions) (result *ServiceID, response *core.DetailedResponse, err error)

ServiceCall<ServiceId> getServiceId(GetServiceIdOptions getServiceIdOptions)
Copy to clipboard

getServiceId(params)

get_service_id(
        self,
        id: str,
        *,
        include_history: Optional[bool] = None,
        include_activity: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.serviceid.get

Request

Instantiate the GetServiceIDOptions struct and set the fields to provide parameter values for the GetServiceID method.

Use the GetServiceIdOptions.Builder to create a GetServiceIdOptions object that contains the parameter values for the getServiceId method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the 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.

Default: false
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.

Default: false

parameter

WithContext method only

GetServiceIdOptions

The GetServiceID options.

GetServiceIdOptions

The getServiceId options.

parameters

id
Required*
string
Unique ID of the service ID.
includeHistory
boolean
Defines if the entity history is included in the response.

Default: false
includeActivity
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.

Default: false

parameters

id
Required*
str
Unique ID of the service ID.
include_history
bool
Defines if the entity history is included in the response.

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

Default: false

Example request

curl -X GET "https://iam.cloud.ibm.com/v1/serviceids/SERVICE_ID_UNIQUE_ID" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" 
Copy to clipboard

Example request

getServiceIDOptions := iamIdentityService.NewGetServiceIDOptions(svcID)

getServiceIDOptions.SetIncludeActivity(false)

serviceID, response, err := iamIdentityService.GetServiceID(getServiceIDOptions)
if err != nil {
  panic(err)
}
svcIDEtag = response.GetHeaders().Get("Etag")
b, _ := json.MarshalIndent(serviceID, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

GetServiceIdOptions getServiceIdOptions = new GetServiceIdOptions.Builder()
    .id(svcId)
    .includeActivity(false)
    .build();

Response<ServiceId> response = service.getServiceId(getServiceIdOptions).execute();
ServiceId serviceId = response.getResult();
svcIdEtag = response.getHeaders().values("Etag").get(0);

System.out.println(serviceId);
Copy to clipboard

Example request

const params = {
  id: svcId,
  includeActivity: true,
};

try {
  const res = await iamIdentityService.getServiceId(params)
  svcIdEtag = res.headers['etag'];
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

response = iam_identity_service.get_service_id(
  id=svc_id,
  include_history=True,
  include_activity=True,
)
service_id = response.get_result()
print(json.dumps(service_id, indent=2))
Copy to clipboard

Response

Response Body

ServiceId

Response body format for service ID V1 REST requests.

ServiceId

Response body format for service ID V1 REST requests.

ServiceId

Response body format for service ID V1 REST requests.

ServiceId

Response body format for service ID V1 REST requests.

ServiceId

Response body format for service ID V1 REST requests.

Status Code

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
service ID with provided ID not found.
500
Internal Server error. Response if unexpected error situation happened.

Example responses

Status 200

{
  "id": "ServiceId-cb36c9a9-778f-4985-a398-dbec6523054a",
  "iam_id": "iam-ServiceId-cb36c9a9-778f-4985-a398-dbec6523054a",
  "entity_tag": "1-b5edc4362f94fb1fa5f009467b1db039",
  "crn": "crn:v1:bluemix:public:iam-identity::a/100abcde100a41abc100aza678abc0zz::serviceid:ServiceId-cb36c9a9-778f-4985-a398-dbec6523054a",
  "locked": false,
  "created_at": "2020-11-10T14:05+0000",
  "modified_at": "2020-11-10T14:05+0000",
  "account_id": "100abcde100a41abc100aza678abc0zz",
  "name": "New-serviceID",
  "description": "New-serviceID-desc",
  "unique_instance_crns": []
}
Copy to clipboard

Success example

{
  "id": "ServiceId-cb36c9a9-778f-4985-a398-dbec6523054a",
  "iam_id": "iam-ServiceId-cb36c9a9-778f-4985-a398-dbec6523054a",
  "entity_tag": "1-b5edc4362f94fb1fa5f009467b1db039",
  "crn": "crn:v1:bluemix:public:iam-identity::a/100abcde100a41abc100aza678abc0zz::serviceid:ServiceId-cb36c9a9-778f-4985-a398-dbec6523054a",
  "locked": false,
  "created_at": "2020-11-10T14:05+0000",
  "modified_at": "2020-11-10T14:05+0000",
  "account_id": "100abcde100a41abc100aza678abc0zz",
  "name": "New-serviceID",
  "description": "New-serviceID-desc",
  "unique_instance_crns": []
}
Copy to clipboard

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.

PUT /v1/serviceids/{id}

(iamIdentity *IamIdentityV1) UpdateServiceID(updateServiceIDOptions *UpdateServiceIDOptions) (result *ServiceID, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) UpdateServiceIDWithContext(ctx context.Context, updateServiceIDOptions *UpdateServiceIDOptions) (result *ServiceID, response *core.DetailedResponse, err error)

ServiceCall<ServiceId> updateServiceId(UpdateServiceIdOptions updateServiceIdOptions)
Copy to clipboard

updateServiceId(params)

update_service_id(
        self,
        id: str,
        if_match: str,
        *,
        name: Optional[str] = None,
        description: Optional[str] = None,
        unique_instance_crns: Optional[List[str]] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.serviceid.update

Auditing

Calling this method generates the following auditing event.

iam-identity.account-serviceid.update

Request

Instantiate the UpdateServiceIDOptions struct and set the fields to provide parameter values for the UpdateServiceID method.

Use the UpdateServiceIdOptions.Builder to create a UpdateServiceIdOptions object that contains the parameter values for the updateServiceId method.

Custom Headers

If-Match
Required*
string
Version of the service ID to be updated. Specify the version that you retrieved as entity_tag (ETag header) when reading the service ID. This value helps identifying parallel usage of this API. Pass * to indicate to update any version available. This might result in stale updates.
Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

id
Required*
string
Unique ID of the service ID to be updated.

Request Body

Required*

UpdateServiceIdRequest

Request to update a service ID.

parameter

WithContext method only

UpdateServiceIdOptions

The UpdateServiceID options.

UpdateServiceIdOptions

The updateServiceId options.

parameters

id
Required*
string
Unique ID of the service ID to be updated.
ifMatch
Required*
string
Version of the service ID to be updated. Specify the version that you retrieved as entity_tag (ETag header) when reading the service ID. This value helps identifying parallel usage of this API. Pass * to indicate to update any version available. This might result in stale updates.
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.
uniqueInstanceCrns
string[]
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.

parameters

id
Required*
str
Unique ID of the service ID to be updated.
if_match
Required*
str
Version of the service ID to be updated. Specify the version that you retrieved as entity_tag (ETag header) when reading the service ID. This value helps identifying parallel usage of this API. Pass * to indicate to update any version available. This might result in stale updates.
name
str
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
str
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
List[str]
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.

Example request

curl -X PUT "https://iam.cloud.ibm.com/v1/serviceids/SERVICE_ID_UNIQUE_ID" --header "Authorization: Bearer $TOKEN" --header "If-Match: <value of etag header from GET request>" --header "Content-Type: application/json" --data '{
    "name": "My-super-secret-serviceid",
    "description": "super secret service ID"
}'
Copy to clipboard

Example request

updateServiceIDOptions := iamIdentityService.NewUpdateServiceIDOptions(svcID, svcIDEtag)
updateServiceIDOptions.SetDescription("This is an updated description")

serviceID, response, err := iamIdentityService.UpdateServiceID(updateServiceIDOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(serviceID, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

UpdateServiceIdOptions updateServiceIdOptions = new UpdateServiceIdOptions.Builder()
    .id(svcId)
    .ifMatch(svcIdEtag)
    .description("This is an updated description")
    .build();

Response<ServiceId> response = service.updateServiceId(updateServiceIdOptions).execute();
ServiceId serviceId = response.getResult();

System.out.println(serviceId);

Example request

const params = {
  id: svcId,
  ifMatch: svcIdEtag,
  description: 'This is an updated description',
};

try {
  const res = await iamIdentityService.updateServiceId(params)
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

service_id = iam_identity_service.update_service_id(
  id=svc_id, if_match=svc_id_etag, description='This is an updated description'
).get_result()
print(json.dumps(service_id, indent=2))
Copy to clipboard

Response

Response Body

ServiceId

Response body format for service ID V1 REST requests.

ServiceId

Response body format for service ID V1 REST requests.

ServiceId

Response body format for service ID V1 REST requests.

ServiceId

Response body format for service ID V1 REST requests.

ServiceId

Response body format for service ID V1 REST requests.

Status Code

200
Successful - service ID updated.
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.

Example responses

Status 200

{
  "id": "ServiceId-cb36c9a9-778f-4985-a398-dbec6523054a",
  "iam_id": "iam-ServiceId-cb36c9a9-778f-4985-a398-dbec6523054a",
  "entity_tag": "2-6dd669bd2257898957b2d117ec93e730",
  "crn": "crn:v1:bluemix:public:iam-identity::a/100abcde100a41abc100aza678abc0zz::serviceid:ServiceId-cb36c9a9-778f-4985-a398-dbec6523054a",
  "locked": false,
  "created_at": "2020-11-10T14:05+0000",
  "modified_at": "2020-11-10T14:13+0000",
  "account_id": "100abcde100a41abc100aza678abc0zz",
  "name": "New-serviceID-updated",
  "description": "New-serviceID-desc-updated",
  "unique_instance_crns": []
}
Copy to clipboard

Success example

{
  "id": "ServiceId-cb36c9a9-778f-4985-a398-dbec6523054a",
  "iam_id": "iam-ServiceId-cb36c9a9-778f-4985-a398-dbec6523054a",
  "entity_tag": "2-6dd669bd2257898957b2d117ec93e730",
  "crn": "crn:v1:bluemix:public:iam-identity::a/100abcde100a41abc100aza678abc0zz::serviceid:ServiceId-cb36c9a9-778f-4985-a398-dbec6523054a",
  "locked": false,
  "created_at": "2020-11-10T14:05+0000",
  "modified_at": "2020-11-10T14:13+0000",
  "account_id": "100abcde100a41abc100aza678abc0zz",
  "name": "New-serviceID-updated",
  "description": "New-serviceID-desc-updated",
  "unique_instance_crns": []
}
Copy to clipboard

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.

DELETE /v1/serviceids/{id}

(iamIdentity *IamIdentityV1) DeleteServiceID(deleteServiceIDOptions *DeleteServiceIDOptions) (response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) DeleteServiceIDWithContext(ctx context.Context, deleteServiceIDOptions *DeleteServiceIDOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> deleteServiceId(DeleteServiceIdOptions deleteServiceIdOptions)
Copy to clipboard

deleteServiceId(params)

delete_service_id(
        self,
        id: str,
        **kwargs,
    ) -> DetailedResponse

Authorization

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

iam-identity.serviceid.delete

Auditing

Calling this method generates the following auditing event.

iam-identity.account-serviceid.delete

Request

Instantiate the DeleteServiceIDOptions struct and set the fields to provide parameter values for the DeleteServiceID method.

Use the DeleteServiceIdOptions.Builder to create a DeleteServiceIdOptions object that contains the parameter values for the deleteServiceId method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

id
Required*
string
Unique ID of the service ID.

parameter

WithContext method only

DeleteServiceIdOptions

The DeleteServiceID options.

DeleteServiceIdOptions

The deleteServiceId options.

parameters

id
Required*
string
Unique ID of the service ID.

parameters

id
Required*
str
Unique ID of the service ID.

Example request

curl -X DELETE "https://iam.cloud.ibm.com/v1/serviceids/SERVICE_ID_UNIQUE_ID" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" 
Copy to clipboard

Example request

deleteServiceIDOptions := iamIdentityService.NewDeleteServiceIDOptions(svcID)

response, err := iamIdentityService.DeleteServiceID(deleteServiceIDOptions)
if err != nil {
  panic(err)
}
Copy to clipboard

Example request

DeleteServiceIdOptions deleteServiceIdOptions = new DeleteServiceIdOptions.Builder()
    .id(svcId)
    .build();

Response<Void> response = service.deleteServiceId(deleteServiceIdOptions).execute();

Example request

const params = {
  id: svcId,
};

try {
  await iamIdentityService.deleteServiceId(params)
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

response = iam_identity_service.delete_service_id(id=svc_id)

Response

Status Code

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.

No Sample Response

This method does not specify any sample responses.

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.

POST /v1/serviceids/{id}/lock

(iamIdentity *IamIdentityV1) LockServiceID(lockServiceIDOptions *LockServiceIDOptions) (response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) LockServiceIDWithContext(ctx context.Context, lockServiceIDOptions *LockServiceIDOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> lockServiceId(LockServiceIdOptions lockServiceIdOptions)
Copy to clipboard

lockServiceId(params)

lock_service_id(
        self,
        id: str,
        **kwargs,
    ) -> DetailedResponse

Authorization

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

iam-identity.serviceid.update

Auditing

Calling this method generates the following auditing event.

iam-identity.account-serviceid.update

Request

Instantiate the LockServiceIDOptions struct and set the fields to provide parameter values for the LockServiceID method.

Use the LockServiceIdOptions.Builder to create a LockServiceIdOptions object that contains the parameter values for the lockServiceId method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

id
Required*
string
Unique ID of the service ID.

parameter

WithContext method only

LockServiceIdOptions

The LockServiceID options.

LockServiceIdOptions

The lockServiceId options.

parameters

id
Required*
string
Unique ID of the service ID.

parameters

id
Required*
str
Unique ID of the service ID.

Example request

curl -X POST "https://iam.cloud.ibm.com/v1/serviceids/SERVICE_ID_UNIQUE_ID/lock" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" 
Copy to clipboard

Example request

lockServiceIDOptions := iamIdentityService.NewLockServiceIDOptions(svcID)

response, err := iamIdentityService.LockServiceID(lockServiceIDOptions)
if err != nil {
  panic(err)
}
Copy to clipboard

Example request

LockServiceIdOptions lockServiceIdOptions = new LockServiceIdOptions.Builder()
    .id(svcId)
    .build();

Response<Void> response = service.lockServiceId(lockServiceIdOptions).execute();

Example request

const params = {
  id: svcId,
};

try {
  await iamIdentityService.lockServiceId(params);
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

response = iam_identity_service.lock_service_id(id=svc_id)

Response

Status Code

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.

No Sample Response

This method does not specify any sample responses.

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.

DELETE /v1/serviceids/{id}/lock

(iamIdentity *IamIdentityV1) UnlockServiceID(unlockServiceIDOptions *UnlockServiceIDOptions) (response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) UnlockServiceIDWithContext(ctx context.Context, unlockServiceIDOptions *UnlockServiceIDOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> unlockServiceId(UnlockServiceIdOptions unlockServiceIdOptions)
Copy to clipboard

unlockServiceId(params)

unlock_service_id(
        self,
        id: str,
        **kwargs,
    ) -> DetailedResponse

Authorization

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

iam-identity.serviceid.update

Auditing

Calling this method generates the following auditing event.

iam-identity.account-serviceid.update

Request

Instantiate the UnlockServiceIDOptions struct and set the fields to provide parameter values for the UnlockServiceID method.

Use the UnlockServiceIdOptions.Builder to create a UnlockServiceIdOptions object that contains the parameter values for the unlockServiceId method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

id
Required*
string
Unique ID of the service ID.

parameter

WithContext method only

UnlockServiceIdOptions

The UnlockServiceID options.

UnlockServiceIdOptions

The unlockServiceId options.

parameters

id
Required*
string
Unique ID of the service ID.

parameters

id
Required*
str
Unique ID of the service ID.

Example request

curl -X DELETE "https://iam.cloud.ibm.com/v1/serviceids/SERVICE_ID_UNIQUE_ID/lock" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" 
Copy to clipboard

Example request

unlockServiceIDOptions := iamIdentityService.NewUnlockServiceIDOptions(svcID)

response, err := iamIdentityService.UnlockServiceID(unlockServiceIDOptions)
if err != nil {
  panic(err)
}
Copy to clipboard

Example request

UnlockServiceIdOptions unlockServiceIdOptions = new UnlockServiceIdOptions.Builder()
    .id(svcId)
    .build();

Response<Void> response = service.unlockServiceId(unlockServiceIdOptions).execute();

Example request

const params = {
  id: svcId,
};

try {
  await iamIdentityService.unlockServiceId(params);
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

response = iam_identity_service.unlock_service_id(id=svc_id)

Response

Status Code

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.

No Sample Response

This method does not specify any sample responses.

Create a trusted profile for a given account ID.

POST /v1/profiles

(iamIdentity *IamIdentityV1) CreateProfile(createProfileOptions *CreateProfileOptions) (result *TrustedProfile, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) CreateProfileWithContext(ctx context.Context, createProfileOptions *CreateProfileOptions) (result *TrustedProfile, response *core.DetailedResponse, err error)

ServiceCall<TrustedProfile> createProfile(CreateProfileOptions createProfileOptions)
Copy to clipboard

createProfile(params)

create_profile(
        self,
        name: str,
        account_id: str,
        *,
        description: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.profile.create

Auditing

Calling this method generates the following auditing event.

iam-identity.profile.create

Request

Instantiate the CreateProfileOptions struct and set the fields to provide parameter values for the CreateProfile method.

Use the CreateProfileOptions.Builder to create a CreateProfileOptions object that contains the parameter values for the createProfile method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Request Body

Required*

CreateTrustedProfileRequest

Request to create a trusted profile.

parameter

WithContext method only

CreateProfileOptions

The CreateProfile options.

CreateProfileOptions

The createProfile options.

parameters

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.
accountId
Required*
string
The account ID of the trusted profile.
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.

parameters

name
Required*
str
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.
account_id
Required*
str
The account ID of the trusted profile.
description
str
The optional description of the trusted profile. The 'description' property is only available if a description was provided during creation of trusted profile.

Example request

curl -X POST "https://iam.cloud.ibm.com/v1/profiles" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" --header "Accept: application/json" --data '{
    "name": "My Nice Profile",
    "description": "My Nice Profile - desc",
    "account_id": "ACCOUNT_ID"
}'
Copy to clipboard

Example request

createProfileOptions := iamIdentityService.NewCreateProfileOptions(profileName, accountID)
createProfileOptions.SetDescription("Example Profile")

profile, response, err := iamIdentityService.CreateProfile(createProfileOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(profile, "", "  ")
fmt.Println(string(b))
profileId = *profile.ID
Copy to clipboard

Example request

CreateProfileOptions createProfileOptions = new CreateProfileOptions.Builder()
    .name(profileName)
    .description("Example Profile")
    .accountId(accountId)
    .build();

Response<TrustedProfile> response = service.createProfile(createProfileOptions).execute();
TrustedProfile profile = response.getResult();
profileId = profile.getId();

System.out.println(profile);

Example request

const params = {
  name: 'profileName',
  description: 'Example Profile',
  accountId,
};

try {
  const res = await iamIdentityService.createProfile(params);
  profileId = res.result.id
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

profile = iam_identity_service.create_profile(
  name="example profile", description="example profile", account_id=account_id
).get_result()
print(json.dumps(profile, indent=2))
Copy to clipboard

Response

Response Body

TrustedProfile

Response body format for trusted profile V1 REST requests.

TrustedProfile

Response body format for trusted profile V1 REST requests.

TrustedProfile

Response body format for trusted profile V1 REST requests.

TrustedProfile

Response body format for trusted profile V1 REST requests.

TrustedProfile

Response body format for trusted profile V1 REST requests.

Status Code

201
Trusted profile successfully created. Response if the Object could be created in the persistence layer.
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.

Example responses

Status 201

{
  "iam_id": "iam-Profile-94497d0d-2ac3-41bf-a993-a49d1b14627c",
  "crn": "crn:v1:bluemix:public:iam-identity::a/18e3020749ce4744b0b472466d61fdb4::profile:Profile-94497d0d-2ac3-41bf-a993-a49d1b14627c",
  "id": "Profile-94497d0d-2ac3-41bf-a993-a49d1b14627c",
  "entity_tag": "1-eb85ef473fd681c90c8743fc13a38119",
  "created_at": "2021-07-28T10:23+0000",
  "modified_at": "2021-07-28T10:23+0000",
  "account_id": "18e3020749ce4744b0b472466d61fdb4",
  "name": "My profile",
  "description": "A superb profile"
}
Copy to clipboard

Success example

{
  "iam_id": "iam-Profile-94497d0d-2ac3-41bf-a993-a49d1b14627c",
  "crn": "crn:v1:bluemix:public:iam-identity::a/18e3020749ce4744b0b472466d61fdb4::profile:Profile-94497d0d-2ac3-41bf-a993-a49d1b14627c",
  "id": "Profile-94497d0d-2ac3-41bf-a993-a49d1b14627c",
  "entity_tag": "1-eb85ef473fd681c90c8743fc13a38119",
  "created_at": "2021-07-28T10:23+0000",
  "modified_at": "2021-07-28T10:23+0000",
  "account_id": "18e3020749ce4744b0b472466d61fdb4",
  "name": "My profile",
  "description": "A superb profile"
}
Copy to clipboard

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

GET /v1/profiles

(iamIdentity *IamIdentityV1) ListProfiles(listProfilesOptions *ListProfilesOptions) (result *TrustedProfilesList, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) ListProfilesWithContext(ctx context.Context, listProfilesOptions *ListProfilesOptions) (result *TrustedProfilesList, response *core.DetailedResponse, err error)

ServiceCall<TrustedProfilesList> listProfiles(ListProfilesOptions listProfilesOptions)
Copy to clipboard

listProfiles(params)

list_profiles(
        self,
        account_id: str,
        *,
        name: Optional[str] = None,
        pagesize: Optional[int] = None,
        sort: Optional[str] = None,
        order: Optional[str] = None,
        include_history: Optional[bool] = None,
        pagetoken: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.profile.get

Auditing

Calling this method generates the following auditing event.

iam-identity.profile.get

Request

Instantiate the ListProfilesOptions struct and set the fields to provide parameter values for the ListProfiles method.

Use the ListProfilesOptions.Builder to create a ListProfilesOptions object that contains the parameter values for the listProfiles method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

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.

Allowable values: [asc,desc]
Default: asc
include_history
boolean
Defines if the entity history is included in the response.

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

parameter

WithContext method only

ListProfilesOptions

The ListProfiles options.

ListProfilesOptions

The listProfiles options.

parameters

accountId
Required*
string
Account ID to query for trusted profiles.
name
string
Name of the trusted profile to query.
pagesize
number
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.

Allowable values: [asc,desc]
Default: asc
includeHistory
boolean
Defines if the entity history is included in the response.

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

parameters

account_id
Required*
str
Account ID to query for trusted profiles.
name
str
Name of the trusted profile to query.
pagesize
int
Optional size of a single page. Default is 20 items per page. Valid range is 1 to 100.
sort
str
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
str
Optional sort order, valid values are asc and desc. Default: asc.

Allowable values: [asc,desc]
Default: asc
include_history
bool
Defines if the entity history is included in the response.

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

Example request

curl -X GET "https://iam.cloud.ibm.com/v1/profiles?account_id=ACCOUNT_ID" --header "Authorization: Bearer $TOKEN" --header "Accept: application/json" 
Copy to clipboard

Example request

listProfilesOptions := iamIdentityService.NewListProfilesOptions(accountID)
listProfilesOptions.SetIncludeHistory(false)

trustedProfiles, response, err := iamIdentityService.ListProfiles(listProfilesOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(trustedProfiles, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

ListProfilesOptions listProfilesOptions = new ListProfilesOptions.Builder()
    .accountId(accountId)
    .includeHistory(false)
    .build();

Response<TrustedProfilesList> response = service.listProfiles(listProfilesOptions).execute();
TrustedProfilesList profiles = response.getResult();

System.out.println(profiles);

Example request

const params = {
  accountId: accountId,
  includeHistory: false,
};

try {
  const res = await iamIdentityService.listProfiles(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

profile_list = iam_identity_service.list_profiles(account_id=account_id, include_history=True).get_result()
print(json.dumps(profile_list, indent=2))
Copy to clipboard

Response

Response Body

TrustedProfilesList

Response body format for the List trusted profiles V1 REST request.

TrustedProfilesList

Response body format for the List trusted profiles V1 REST request.

TrustedProfilesList

Response body format for the List trusted profiles V1 REST request.

TrustedProfilesList

Response body format for the List trusted profiles V1 REST request.

TrustedProfilesList

Response body format for the List trusted profiles V1 REST request.

Status Code

200
Successful operation.
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
account_id does not match Authorization token, account_id not found.
500
Internal Server error.

Example responses

Status 200

{
  "offset": 0,
  "limit": 20,
  "first": "https://iam.cloud.ibm.com/v1/profiles?account_id=18e3020749ce4744b0b472466d61fdb4",
  "profiles": [
    {
      "id": "Profile-94188726-7725-4c78-a686-b5deb4d47cb5",
      "entity_tag": "5-29d5f70272e5f13930938ca32f30223d",
      "crn": "crn:v1:bluemix:public:iam-identity::a/18e3020749ce4744b0b472466d61fdb4::profile:Profile-94188726-7725-4c78-a686-b5deb4d47cb5",
      "name": "My profile v1",
      "description": "A superb profile v1",
      "created_at": "2021-07-28T09:59+0000",
      "modified_at": "2021-07-28T16:29+0000",
      "iam_id": "iam-Profile-94188726-7725-4c78-a686-b5deb4d47cb5",
      "account_id": "18e3020749ce4744b0b472466d61fdb4",
      "ims_account_id": 8794967,
      "ims_user_id": 234876
    }
  ]
}
Copy to clipboard

Success example

{
  "offset": 0,
  "limit": 20,
  "first": "https://iam.cloud.ibm.com/v1/profiles?account_id=18e3020749ce4744b0b472466d61fdb4",
  "profiles": [
    {
      "id": "Profile-94188726-7725-4c78-a686-b5deb4d47cb5",
      "entity_tag": "5-29d5f70272e5f13930938ca32f30223d",
      "crn": "crn:v1:bluemix:public:iam-identity::a/18e3020749ce4744b0b472466d61fdb4::profile:Profile-94188726-7725-4c78-a686-b5deb4d47cb5",
      "name": "My profile v1",
      "description": "A superb profile v1",
      "created_at": "2021-07-28T09:59+0000",
      "modified_at": "2021-07-28T16:29+0000",
      "iam_id": "iam-Profile-94188726-7725-4c78-a686-b5deb4d47cb5",
      "account_id": "18e3020749ce4744b0b472466d61fdb4",
      "ims_account_id": 8794967,
      "ims_user_id": 234876
    }
  ]
}
Copy to clipboard

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.

GET /v1/profiles/{profile-id}

(iamIdentity *IamIdentityV1) GetProfile(getProfileOptions *GetProfileOptions) (result *TrustedProfile, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) GetProfileWithContext(ctx context.Context, getProfileOptions *GetProfileOptions) (result *TrustedProfile, response *core.DetailedResponse, err error)

ServiceCall<TrustedProfile> getProfile(GetProfileOptions getProfileOptions)
Copy to clipboard

getProfile(params)

get_profile(
        self,
        profile_id: str,
        *,
        include_activity: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.profile.get

Auditing

Calling this method generates the following auditing event.

iam-identity.profile.get

Request

Instantiate the GetProfileOptions struct and set the fields to provide parameter values for the GetProfile method.

Use the GetProfileOptions.Builder to create a GetProfileOptions object that contains the parameter values for the getProfile method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the 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.

Default: false

parameter

WithContext method only

GetProfileOptions

The GetProfile options.

GetProfileOptions

The getProfile options.

parameters

profileId
Required*
string
ID of the trusted profile to get.
includeActivity
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.

Default: false

parameters

profile_id
Required*
str
ID of the trusted profile to get.
include_activity
bool
Defines if the entity's activity is included in the response. Retrieving activity data is an expensive operation, so only request this when needed.

Default: false

Example request

curl -X GET "https://iam.cloud.ibm.com/v1/profiles/PROFILE_ID" --header "Authorization: Bearer $TOKEN" --header "Accept: application/json" 
Copy to clipboard

Example request

getProfileOptions := iamIdentityService.NewGetProfileOptions(profileId)

getProfileOptions.SetIncludeActivity(false)

profile, response, err := iamIdentityService.GetProfile(getProfileOptions)
if err != nil {
  panic(err)
}
profileEtag = response.GetHeaders().Get("Etag")
b, _ := json.MarshalIndent(profile, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

GetProfileOptions getProfileOptions = new GetProfileOptions.Builder()
    .profileId(profileId)
    .includeActivity(false)
    .build();

Response<TrustedProfile> response = service.getProfile(getProfileOptions).execute();
TrustedProfile profile = response.getResult();
profileEtag = response.getHeaders().values("Etag").get(0);

System.out.println(profile);
Copy to clipboard

Example request

const params = {
  profileId,
  includeActivity: true,
};

try {
  const res = await iamIdentityService.getProfile(params)
  profileEtag = res.headers['etag'];
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

response = iam_identity_service.get_profile(
  profile_id=profile_id,
  include_activity=True,
)
profile = response.get_result()
print(json.dumps(profile, indent=2))
Copy to clipboard

Response

Response Body

TrustedProfile

Response body format for trusted profile V1 REST requests.

TrustedProfile

Response body format for trusted profile V1 REST requests.

TrustedProfile

Response body format for trusted profile V1 REST requests.

TrustedProfile

Response body format for trusted profile V1 REST requests.

TrustedProfile

Response body format for trusted profile V1 REST requests.

Status Code

200
Successful - Get of Trusted profile.
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.

Example responses

Status 200

{
  "id": "Profile-94188726-7725-4c78-a686-b5deb4d47cb5",
  "entity_tag": "5-29d5f70272e5f13930938ca32f30223d",
  "crn": "crn:v1:bluemix:public:iam-identity::a/18e3020749ce4744b0b472466d61fdb4::profile:Profile-94188726-7725-4c78-a686-b5deb4d47cb5",
  "name": "My profile v1",
  "description": "A superb profile v1",
  "created_at": "2021-07-28T09:59+0000",
  "modified_at": "2021-07-28T16:29+0000",
  "iam_id": "iam-Profile-94188726-7725-4c78-a686-b5deb4d47cb5",
  "account_id": "18e3020749ce4744b0b472466d61fdb4",
  "ims_account_id": 8794967,
  "ims_user_id": 234876
}
Copy to clipboard

Success example

{
  "id": "Profile-94188726-7725-4c78-a686-b5deb4d47cb5",
  "entity_tag": "5-29d5f70272e5f13930938ca32f30223d",
  "crn": "crn:v1:bluemix:public:iam-identity::a/18e3020749ce4744b0b472466d61fdb4::profile:Profile-94188726-7725-4c78-a686-b5deb4d47cb5",
  "name": "My profile v1",
  "description": "A superb profile v1",
  "created_at": "2021-07-28T09:59+0000",
  "modified_at": "2021-07-28T16:29+0000",
  "iam_id": "iam-Profile-94188726-7725-4c78-a686-b5deb4d47cb5",
  "account_id": "18e3020749ce4744b0b472466d61fdb4",
  "ims_account_id": 8794967,
  "ims_user_id": 234876
}
Copy to clipboard

Update the name or description of an existing trusted profile.

PUT /v1/profiles/{profile-id}

(iamIdentity *IamIdentityV1) UpdateProfile(updateProfileOptions *UpdateProfileOptions) (result *TrustedProfile, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) UpdateProfileWithContext(ctx context.Context, updateProfileOptions *UpdateProfileOptions) (result *TrustedProfile, response *core.DetailedResponse, err error)

ServiceCall<TrustedProfile> updateProfile(UpdateProfileOptions updateProfileOptions)
Copy to clipboard

updateProfile(params)

update_profile(
        self,
        profile_id: str,
        if_match: str,
        *,
        name: Optional[str] = None,
        description: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.profile.update

Auditing

Calling this method generates the following auditing event.

iam-identity.profile.update

Request

Instantiate the UpdateProfileOptions struct and set the fields to provide parameter values for the UpdateProfile method.

Use the UpdateProfileOptions.Builder to create a UpdateProfileOptions object that contains the parameter values for the updateProfile method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.
If-Match
Required*
string
Version of the trusted profile to be updated. Specify the version that you retrived when reading list of trusted profiles. This value helps to identify any parallel usage of trusted profile. Pass * to indicate to update any version available. This might result in stale updates.

Path Parameters

profile-id
Required*
string
ID of the trusted profile to be updated.

Request Body

Required*

UpdateTrustedProfileRequest

Request to update a trusted profile.

parameter

WithContext method only

UpdateProfileOptions

The UpdateProfile options.

UpdateProfileOptions

The updateProfile options.

parameters

profileId
Required*
string
ID of the trusted profile to be updated.
ifMatch
Required*
string
Version of the trusted profile to be updated. Specify the version that you retrived when reading list of trusted profiles. This value helps to identify any parallel usage of trusted profile. Pass * to indicate to update any version available. This might result in stale updates.
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.

parameters

profile_id
Required*
str
ID of the trusted profile to be updated.
if_match
Required*
str
Version of the trusted profile to be updated. Specify the version that you retrived when reading list of trusted profiles. This value helps to identify any parallel usage of trusted profile. Pass * to indicate to update any version available. This might result in stale updates.
name
str
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
str
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.

Example request

curl -X PUT "https://iam.cloud.ibm.com/v1/profiles/PROFILE_ID" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" --header "Accept: application/json" --header "If-Match: <value of etag header from GET request>" --data '{
    "name": "My Profile updated",
    "description": "My updated desc"
}'
Copy to clipboard

Example request

updateProfileOptions := iamIdentityService.NewUpdateProfileOptions(profileId, profileEtag)
updateProfileOptions.SetDescription("This is an updated description")

profile, response, err := iamIdentityService.UpdateProfile(updateProfileOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(profile, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

String newDescription = "updated description";
UpdateProfileOptions updateProfileOptions = new UpdateProfileOptions.Builder()
    .profileId(profileId)
    .ifMatch(profileEtag)
    .description(newDescription)
    .build();

Response<TrustedProfile> response = service.updateProfile(updateProfileOptions).execute();
TrustedProfile profile = response.getResult();

System.out.println(profile);

Example request

const params = {
  profileId: profileId,
  ifMatch: profileEtag,
  description: 'This is an updated description',
};

try {
  const res = await iamIdentityService.updateProfile(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

profile = iam_identity_service.update_profile(
  profile_id=profile_id, if_match=profile_etag, description='This is an updated description'
).get_result()

print(json.dumps(profile, indent=2))
Copy to clipboard

Response

Response Body

TrustedProfile

Response body format for trusted profile V1 REST requests.

TrustedProfile

Response body format for trusted profile V1 REST requests.

TrustedProfile

Response body format for trusted profile V1 REST requests.

TrustedProfile

Response body format for trusted profile V1 REST requests.

TrustedProfile

Response body format for trusted profile V1 REST requests.

Status Code

200
Successful - Trusted profile updated.
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.

Example responses

Status 200

{
  "id": "Profile-94188726-7725-4c78-a686-b5deb4d47cb5",
  "entity_tag": "5-29d5f70272e5f13930938ca32f30223d",
  "crn": "crn:v1:bluemix:public:iam-identity::a/18e3020749ce4744b0b472466d61fdb4::profile:Profile-94188726-7725-4c78-a686-b5deb4d47cb5",
  "name": "My profile updated",
  "description": "A superb profile updated",
  "created_at": "2021-07-28T09:59+0000",
  "modified_at": "2021-07-28T16:29+0000",
  "iam_id": "iam-Profile-94188726-7725-4c78-a686-b5deb4d47cb5",
  "account_id": "18e3020749ce4744b0b472466d61fdb4",
  "ims_account_id": 8794967,
  "ims_user_id": 234876
}
Copy to clipboard

Success example

{
  "id": "Profile-94188726-7725-4c78-a686-b5deb4d47cb5",
  "entity_tag": "5-29d5f70272e5f13930938ca32f30223d",
  "crn": "crn:v1:bluemix:public:iam-identity::a/18e3020749ce4744b0b472466d61fdb4::profile:Profile-94188726-7725-4c78-a686-b5deb4d47cb5",
  "name": "My profile updated",
  "description": "A superb profile updated",
  "created_at": "2021-07-28T09:59+0000",
  "modified_at": "2021-07-28T16:29+0000",
  "iam_id": "iam-Profile-94188726-7725-4c78-a686-b5deb4d47cb5",
  "account_id": "18e3020749ce4744b0b472466d61fdb4",
  "ims_account_id": 8794967,
  "ims_user_id": 234876
}
Copy to clipboard

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.

DELETE /v1/profiles/{profile-id}

(iamIdentity *IamIdentityV1) DeleteProfile(deleteProfileOptions *DeleteProfileOptions) (response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) DeleteProfileWithContext(ctx context.Context, deleteProfileOptions *DeleteProfileOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> deleteProfile(DeleteProfileOptions deleteProfileOptions)
Copy to clipboard

deleteProfile(params)

delete_profile(
        self,
        profile_id: str,
        **kwargs,
    ) -> DetailedResponse

Authorization

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

iam-identity.profile.delete

Auditing

Calling this method generates the following auditing event.

iam-identity.profile.delete

Request

Instantiate the DeleteProfileOptions struct and set the fields to provide parameter values for the DeleteProfile method.

Use the DeleteProfileOptions.Builder to create a DeleteProfileOptions object that contains the parameter values for the deleteProfile method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

profile-id
Required*
string
ID of the trusted profile.

parameter

WithContext method only

DeleteProfileOptions

The DeleteProfile options.

DeleteProfileOptions

The deleteProfile options.

parameters

profileId
Required*
string
ID of the trusted profile.

parameters

profile_id
Required*
str
ID of the trusted profile.

Example request

curl -X DELETE "https://iam.cloud.ibm.com/v1/profiles/PROFILE_ID" --header "Authorization: Bearer $TOKEN"
Copy to clipboard

Example request

deleteProfileOptions := iamIdentityService.NewDeleteProfileOptions(profileId)

response, err := iamIdentityService.DeleteProfile(deleteProfileOptions)
if err != nil {
  panic(err)
}
Copy to clipboard

Example request

DeleteProfileOptions deleteProfileOptions = new DeleteProfileOptions.Builder()
    .profileId(profileId)
    .build();

Response<Void> response = service.deleteProfile(deleteProfileOptions).execute();

Example request

const params = {
  profileId
};

try {
  await iamIdentityService.deleteProfile(params);
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

response = iam_identity_service.delete_profile(profile_id=profile_id)

Response

Status Code

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.

No Sample Response

This method does not specify any sample responses.

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

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

(iamIdentity *IamIdentityV1) CreateClaimRule(createClaimRuleOptions *CreateClaimRuleOptions) (result *ProfileClaimRule, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) CreateClaimRuleWithContext(ctx context.Context, createClaimRuleOptions *CreateClaimRuleOptions) (result *ProfileClaimRule, response *core.DetailedResponse, err error)

ServiceCall<ProfileClaimRule> createClaimRule(CreateClaimRuleOptions createClaimRuleOptions)
Copy to clipboard

createClaimRule(params)

create_claim_rule(
        self,
        profile_id: str,
        type: str,
        conditions: List['ProfileClaimRuleConditions'],
        *,
        context: Optional['ResponseContext'] = None,
        name: Optional[str] = None,
        realm_name: Optional[str] = None,
        cr_type: Optional[str] = None,
        expiration: Optional[int] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.profile.update

Auditing

Calling this method generates the following auditing event.

iam-identity.profile.update

Request

Instantiate the CreateClaimRuleOptions struct and set the fields to provide parameter values for the CreateClaimRule method.

Use the CreateClaimRuleOptions.Builder to create a CreateClaimRuleOptions object that contains the parameter values for the createClaimRule method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

profile-id
Required*
string
ID of the trusted profile to create a claim rule.

Request Body

Required*

ProfileClaimRuleRequest

Request to create a claim rule for trusted profile.

parameter

WithContext method only

CreateClaimRuleOptions

The CreateClaimRule options.

CreateClaimRuleOptions

The createClaimRule options.

parameters

profileId
Required*
string
ID of the trusted profile to create a claim rule.
type
Required*
string
Type of the claim rule, either 'Profile-SAML' or 'Profile-CR'.
conditions
Required*
Conditions of this claim rule.
context
Context with key properties for problem determination.
name
string
Name of the claim rule to be created or updated.
realmName
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'.
crType
string
The compute resource type the rule applies to, required only if type is specified as 'Profile-CR'. Valid values are VSI, IKS_SA, ROKS_SA.
expiration
number
Session expiration in seconds, only required if type is 'Profile-SAML'.

parameters

profile_id
Required*
str
ID of the trusted profile to create a claim rule.
type
Required*
str
Type of the claim rule, either 'Profile-SAML' or 'Profile-CR'.
conditions
Required*
Conditions of this claim rule.
context
Context with key properties for problem determination.
name
str
Name of the claim rule to be created or updated.
realm_name
str
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
str
The compute resource type the rule applies to, required only if type is specified as 'Profile-CR'. Valid values are VSI, IKS_SA, ROKS_SA.
expiration
int
Session expiration in seconds, only required if type is 'Profile-SAML'.

Example request

curl -X POST "https://iam.cloud.ibm.com/v1/profiles/PROFILE_ID/rules" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" --header "Accept: application/json" --data '{
    "type": "Profile-SAML",
    "realm_name": "https://www.example.org/my-nice-idp",
    "expiration": 43200,
    "conditions": [
     {
         "claim": "groups",
         "operator": "EQUALS",
         "value": "\"cloud-docs-dev\""
     }
     ]
}'
Copy to clipboard

Example request

profileClaimRuleConditions := new(iamidentityv1.ProfileClaimRuleConditions)
profileClaimRuleConditions.Claim = core.StringPtr("blueGroups")
profileClaimRuleConditions.Operator = core.StringPtr("EQUALS")
profileClaimRuleConditions.Value = core.StringPtr("\"cloud-docs-dev\"")

createClaimRuleOptions := iamIdentityService.NewCreateClaimRuleOptions(profileId, claimRuleType, []iamidentityv1.ProfileClaimRuleConditions{*profileClaimRuleConditions})
createClaimRuleOptions.SetName("claimRule")
createClaimRuleOptions.SetRealmName(realmName)
createClaimRuleOptions.SetExpiration(int64(43200))

claimRule, response, err := iamIdentityService.CreateClaimRule(createClaimRuleOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(claimRule, "", "  ")
fmt.Println(string(b))
claimRuleId = *claimRule.ID
Copy to clipboard

Example request

ProfileClaimRuleConditions condition = new ProfileClaimRuleConditions.Builder()
    .claim("blueGroups")
    .operator("EQUALS")
    .value("\"cloud-docs-dev\"")
    .build();

List<ProfileClaimRuleConditions> conditions = new ArrayList<>();
conditions.add(condition);

CreateClaimRuleOptions createClaimRuleOptions = new CreateClaimRuleOptions.Builder()
    .profileId(profileId)
    .type(claimRuleType)
    .realmName(realmName)
    .expiration(43200)
    .conditions(conditions)
    .build();

Response<ProfileClaimRule> response = service.createClaimRule(createClaimRuleOptions).execute();
ProfileClaimRule claimRule = response.getResult();
claimRuleId = claimRule.getId();

System.out.println(claimRule);
Copy to clipboard

Example request

const val = "{'Europe_Group'}";
const profileClaimRuleConditionsModel = {
  claim: 'blueGroups',
  operator: 'EQUALS',
  value: JSON.stringify(val),
};

const conditions = [profileClaimRuleConditionsModel];

const params = {
  profileId: profileId,
  type: 'Profile-SAML',
  realmName: realmName,
  expiration: 43200,
  conditions,
};

try {
  const res = await iamIdentityService.createClaimRule(params);
  claimRuleId = res.result.id
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

profile_claim_rule_conditions_model = {}
profile_claim_rule_conditions_model['claim'] = 'blueGroups'
profile_claim_rule_conditions_model['operator'] = 'EQUALS'
profile_claim_rule_conditions_model['value'] = '\"cloud-docs-dev\"'
claimRule = iam_identity_service.create_claim_rule(
  profile_id=profile_id,
  type='Profile-SAML',
  realm_name='https://sdk.test.realm/1234',
  expiration=43200,
  conditions=[profile_claim_rule_conditions_model],
).get_result()
print(json.dumps(claimRule, indent=2))
Copy to clipboard

Response

Response Body

ProfileClaimRule

Status Code

201
Successful operation.
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.

Example responses

Status 201

{
  "id": "ClaimRule-faa0b1f4-d9e0-42f3-b61c-3927db1cef9b",
  "entity_tag": "1-cd52f1eaf1e7464f9ba30f37c5c5fe32",
  "created_at": "2021-07-28T10:23+0000",
  "modified_at": "2021-07-28T10:23+0000",
  "name": "My Claim rule",
  "type": "Profile-SAML",
  "realm_name": "https://www.example.org/my-nice-idp",
  "expiration": 3600,
  "conditions": {
    "claim": "groups",
    "operator": "EQUALS",
    "value": "\"cloud-docs-dev\""
  }
}
Copy to clipboard

Success example

{
  "id": "ClaimRule-faa0b1f4-d9e0-42f3-b61c-3927db1cef9b",
  "entity_tag": "1-cd52f1eaf1e7464f9ba30f37c5c5fe32",
  "created_at": "2021-07-28T10:23+0000",
  "modified_at": "2021-07-28T10:23+0000",
  "name": "My Claim rule",
  "type": "Profile-SAML",
  "realm_name": "https://www.example.org/my-nice-idp",
  "expiration": 3600,
  "conditions": {
    "claim": "groups",
    "operator": "EQUALS",
    "value": "\"cloud-docs-dev\""
  }
}
Copy to clipboard

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.

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

(iamIdentity *IamIdentityV1) ListClaimRules(listClaimRulesOptions *ListClaimRulesOptions) (result *ProfileClaimRuleList, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) ListClaimRulesWithContext(ctx context.Context, listClaimRulesOptions *ListClaimRulesOptions) (result *ProfileClaimRuleList, response *core.DetailedResponse, err error)

ServiceCall<ProfileClaimRuleList> listClaimRules(ListClaimRulesOptions listClaimRulesOptions)
Copy to clipboard

listClaimRules(params)

list_claim_rules(
        self,
        profile_id: str,
        **kwargs,
    ) -> DetailedResponse

Authorization

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

iam-identity.profile.get

Auditing

Calling this method generates the following auditing event.

iam-identity.profile.get

Request

Instantiate the ListClaimRulesOptions struct and set the fields to provide parameter values for the ListClaimRules method.

Use the ListClaimRulesOptions.Builder to create a ListClaimRulesOptions object that contains the parameter values for the listClaimRules method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

profile-id
Required*
string
ID of the trusted profile.

parameter

WithContext method only

ListClaimRulesOptions

The ListClaimRules options.

ListClaimRulesOptions

The listClaimRules options.

parameters

profileId
Required*
string
ID of the trusted profile.

parameters

profile_id
Required*
str
ID of the trusted profile.

Example request

curl -X GET "https://iam.cloud.ibm.com/v1/profiles/PROFILE_ID/rules" --header "Authorization: Bearer $TOKEN" --header "Accept: application/json" 
Copy to clipboard

Example request

listClaimRulesOptions := iamIdentityService.NewListClaimRulesOptions(profileId)

claimRulesList, response, err := iamIdentityService.ListClaimRules(listClaimRulesOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(claimRulesList, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

ListClaimRulesOptions listClaimRulesOptions = new ListClaimRulesOptions.Builder()
    .profileId(profileId)
    .build();

Response<ProfileClaimRuleList> response = service.listClaimRules(listClaimRulesOptions).execute();
ProfileClaimRuleList claimRules = response.getResult();

System.out.println(claimRules);

Example request

const params = {
  profileId,
};

try {
  const res = await iamIdentityService.listClaimRules(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

claimRule_list = iam_identity_service.list_claim_rules(
  profile_id=profile_id,
).get_result()
print(json.dumps(claimRule_list, indent=2))

Response

Response Body

ProfileClaimRuleList

Status Code

200
Successful operation.
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 ID does not match Authorization token, Trusted profile ID not found.
500
Internal Server error.

Example responses

Status 200

{
  "rules": [
    {
      "id": "ClaimRule-faa0b1f4-d9e0-42f3-b61c-3927db1cef9b",
      "entity_tag": "1-cd52f1eaf1e7464f9ba30f37c5c5fe32",
      "created_at": "2021-07-28T10:23+0000",
      "modified_at": "2021-07-28T10:23+0000",
      "name": "My Claim rule",
      "type": "Profile-SAML",
      "realm_name": "https://www.example.org/my-nice-idp",
      "expiration": 3600,
      "conditions": [
        {
          "claim": "groups",
          "operator": "EQUALS",
          "value": "\"cloud-docs-dev\""
        }
      ]
    }
  ]
}
Copy to clipboard

Success example

{
  "rules": [
    {
      "id": "ClaimRule-faa0b1f4-d9e0-42f3-b61c-3927db1cef9b",
      "entity_tag": "1-cd52f1eaf1e7464f9ba30f37c5c5fe32",
      "created_at": "2021-07-28T10:23+0000",
      "modified_at": "2021-07-28T10:23+0000",
      "name": "My Claim rule",
      "type": "Profile-SAML",
      "realm_name": "https://www.example.org/my-nice-idp",
      "expiration": 3600,
      "conditions": [
        {
          "claim": "groups",
          "operator": "EQUALS",
          "value": "\"cloud-docs-dev\""
        }
      ]
    }
  ]
}
Copy to clipboard

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

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

(iamIdentity *IamIdentityV1) GetClaimRule(getClaimRuleOptions *GetClaimRuleOptions) (result *ProfileClaimRule, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) GetClaimRuleWithContext(ctx context.Context, getClaimRuleOptions *GetClaimRuleOptions) (result *ProfileClaimRule, response *core.DetailedResponse, err error)

ServiceCall<ProfileClaimRule> getClaimRule(GetClaimRuleOptions getClaimRuleOptions)
Copy to clipboard

getClaimRule(params)

get_claim_rule(
        self,
        profile_id: str,
        rule_id: str,
        **kwargs,
    ) -> DetailedResponse

Authorization

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

iam-identity.profile.get

Auditing

Calling this method generates the following auditing event.

iam-identity.profile.get

Request

Instantiate the GetClaimRuleOptions struct and set the fields to provide parameter values for the GetClaimRule method.

Use the GetClaimRuleOptions.Builder to create a GetClaimRuleOptions object that contains the parameter values for the getClaimRule method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

profile-id
Required*
string
ID of the trusted profile.
rule-id
Required*
string
ID of the claim rule to get.

parameter

WithContext method only

GetClaimRuleOptions

The GetClaimRule options.

GetClaimRuleOptions

The getClaimRule options.

parameters

profileId
Required*
string
ID of the trusted profile.
ruleId
Required*
string
ID of the claim rule to get.

parameters

profile_id
Required*
str
ID of the trusted profile.
rule_id
Required*
str
ID of the claim rule to get.

Example request

curl -X GET "https://iam.cloud.ibm.com/v1/profiles/PROFILE_ID/rules/CLAIM_RULE_ID" --header "Authorization: Bearer $TOKEN" --header "Accept: application/json" 
Copy to clipboard

Example request

getClaimRuleOptions := iamIdentityService.NewGetClaimRuleOptions(profileId, claimRuleId)

claimRule, response, err := iamIdentityService.GetClaimRule(getClaimRuleOptions)
if err != nil {
  panic(err)
}
claimRuleEtag = response.GetHeaders().Get("Etag")
b, _ := json.MarshalIndent(claimRule, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

GetClaimRuleOptions getClaimRuleOptions = new GetClaimRuleOptions.Builder()
    .profileId(profileId)
    .ruleId(claimRuleId)
    .build();

Response<ProfileClaimRule> response = service.getClaimRule(getClaimRuleOptions).execute();
ProfileClaimRule claimRule = response.getResult();
claimRuleEtag = response.getHeaders().values("Etag").get(0);

System.out.println(claimRule);
Copy to clipboard

Example request

const params = {
  profileId,
  ruleId: claimRuleId,
};

try {
  const res = await iamIdentityService.getClaimRule(params);
  claimRuleEtag = res.headers['etag'];
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

response = iam_identity_service.get_claim_rule(profile_id=profile_id, rule_id=claimRule_id)
claimRule = response.get_result()
print(json.dumps(claimRule, indent=2))

Response

Response Body

ProfileClaimRule

Status Code

200
Successful - Get of 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.

Example responses

Status 200

{
  "id": "ClaimRule-faa0b1f4-d9e0-42f3-b61c-3927db1cef9b",
  "entity_tag": "1-cd52f1eaf1e7464f9ba30f37c5c5fe32",
  "created_at": "2021-07-28T10:23+0000",
  "modified_at": "2021-07-28T10:23+0000",
  "name": "My Claim rule",
  "type": "Profile-SAML",
  "realm_name": "https://www.example.org/my-nice-idp",
  "expiration": 3600,
  "conditions": {
    "claim": "groups",
    "operator": "EQUALS",
    "value": "\"cloud-docs-dev\""
  }
}
Copy to clipboard

Success example

{
  "id": "ClaimRule-faa0b1f4-d9e0-42f3-b61c-3927db1cef9b",
  "entity_tag": "1-cd52f1eaf1e7464f9ba30f37c5c5fe32",
  "created_at": "2021-07-28T10:23+0000",
  "modified_at": "2021-07-28T10:23+0000",
  "name": "My Claim rule",
  "type": "Profile-SAML",
  "realm_name": "https://www.example.org/my-nice-idp",
  "expiration": 3600,
  "conditions": {
    "claim": "groups",
    "operator": "EQUALS",
    "value": "\"cloud-docs-dev\""
  }
}
Copy to clipboard

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

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

(iamIdentity *IamIdentityV1) UpdateClaimRule(updateClaimRuleOptions *UpdateClaimRuleOptions) (result *ProfileClaimRule, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) UpdateClaimRuleWithContext(ctx context.Context, updateClaimRuleOptions *UpdateClaimRuleOptions) (result *ProfileClaimRule, response *core.DetailedResponse, err error)

ServiceCall<ProfileClaimRule> updateClaimRule(UpdateClaimRuleOptions updateClaimRuleOptions)
Copy to clipboard

updateClaimRule(params)

update_claim_rule(
        self,
        profile_id: str,
        rule_id: str,
        if_match: str,
        type: str,
        conditions: List['ProfileClaimRuleConditions'],
        *,
        context: Optional['ResponseContext'] = None,
        name: Optional[str] = None,
        realm_name: Optional[str] = None,
        cr_type: Optional[str] = None,
        expiration: Optional[int] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.profile.update

Auditing

Calling this method generates the following auditing event.

iam-identity.profile.update

Request

Instantiate the UpdateClaimRuleOptions struct and set the fields to provide parameter values for the UpdateClaimRule method.

Use the UpdateClaimRuleOptions.Builder to create a UpdateClaimRuleOptions object that contains the parameter values for the updateClaimRule method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.
If-Match
Required*
string
Version of the claim rule to be updated. Specify the version that you retrived when reading list of claim rules. This value helps to identify any parallel usage of claim rule. Pass * to indicate to update any version available. This might result in stale updates.

Path Parameters

profile-id
Required*
string
ID of the trusted profile.
rule-id
Required*
string
ID of the claim rule to update.

Request Body

Required*

ProfileClaimRuleRequest

Request to update a claim rule.

parameter

WithContext method only

UpdateClaimRuleOptions

The UpdateClaimRule options.

UpdateClaimRuleOptions

The updateClaimRule options.

parameters

profileId
Required*
string
ID of the trusted profile.
ruleId
Required*
string
ID of the claim rule to update.
ifMatch
Required*
string
Version of the claim rule to be updated. Specify the version that you retrived when reading list of claim rules. This value helps to identify any parallel usage of claim rule. Pass * to indicate to update any version available. This might result in stale updates.
type
Required*
string
Type of the claim rule, either 'Profile-SAML' or 'Profile-CR'.
conditions
Required*
Conditions of this claim rule.
context
Context with key properties for problem determination.
name
string
Name of the claim rule to be created or updated.
realmName
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'.
crType
string
The compute resource type the rule applies to, required only if type is specified as 'Profile-CR'. Valid values are VSI, IKS_SA, ROKS_SA.
expiration
number
Session expiration in seconds, only required if type is 'Profile-SAML'.

parameters

profile_id
Required*
str
ID of the trusted profile.
rule_id
Required*
str
ID of the claim rule to update.
if_match
Required*
str
Version of the claim rule to be updated. Specify the version that you retrived when reading list of claim rules. This value helps to identify any parallel usage of claim rule. Pass * to indicate to update any version available. This might result in stale updates.
type
Required*
str
Type of the claim rule, either 'Profile-SAML' or 'Profile-CR'.
conditions
Required*
Conditions of this claim rule.
context
Context with key properties for problem determination.
name
str
Name of the claim rule to be created or updated.
realm_name
str
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
str
The compute resource type the rule applies to, required only if type is specified as 'Profile-CR'. Valid values are VSI, IKS_SA, ROKS_SA.
expiration
int
Session expiration in seconds, only required if type is 'Profile-SAML'.

Example request

curl -X PUT "https://iam.cloud.ibm.com/v1/profiles/PROFILE_ID/rules/CLAIM_RULE_ID" --header "Authorization: Bearer $TOKEN" --header "If-Match: <value of etag header from GET request>" --header "Content-Type: application/json" --header "Accept: application/json" --data '{
    "type": "Profile-SAML",
    "realm_name": "https://w3id.sso.ibm.com/auth/sps/samlidp2/saml20",
    "expiration": 10000,
    "conditions": [
     {
        "claim": "groups",
        "operator": "CONTAINS",
[object Object]     }
     ]
}'
Copy to clipboard

Example request

profileClaimRuleConditions := new(iamidentityv1.ProfileClaimRuleConditions)
profileClaimRuleConditions.Claim = core.StringPtr("blueGroups")
profileClaimRuleConditions.Operator = core.StringPtr("EQUALS")
profileClaimRuleConditions.Value = core.StringPtr("\"Europe_Group\"")

updateClaimRuleOptions := iamIdentityService.NewUpdateClaimRuleOptions(profileId, claimRuleId, claimRuleEtag, claimRuleType, []iamidentityv1.ProfileClaimRuleConditions{*profileClaimRuleConditions})
updateClaimRuleOptions.SetRealmName(realmName)
updateClaimRuleOptions.SetExpiration(int64(33200))

claimRule, response, err := iamIdentityService.UpdateClaimRule(updateClaimRuleOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(claimRule, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

ProfileClaimRuleConditions condition = new ProfileClaimRuleConditions.Builder()
    .claim("blueGroups")
    .operator("CONTAINS")
    .value("\"Europe_Group\"")
    .build();

List<ProfileClaimRuleConditions> conditions = new ArrayList<>();
conditions.add(condition);

UpdateClaimRuleOptions updateClaimRuleOptions = new UpdateClaimRuleOptions.Builder()
    .profileId(profileId)
    .ruleId(claimRuleId)
    .ifMatch(claimRuleEtag)
    .expiration(33200)
    .conditions(conditions)
    .type(claimRuleType)
    .realmName(realmName)
    .build();

Response<ProfileClaimRule> response = service.updateClaimRule(updateClaimRuleOptions).execute();
ProfileClaimRule claimRule = response.getResult();

System.out.println(claimRule);
Copy to clipboard

Example request

const val = "{'Europe_Group'}";
const profileClaimRuleConditionsModel = {
  claim: 'blueGroups',
  operator: 'EQUALS',
  value: JSON.stringify(val),
};

const conditions = [profileClaimRuleConditionsModel];

const params = {
  profileId,
  ruleId: claimRuleId,
  ifMatch: claimRuleEtag,
  type: 'Profile-SAML',
  realmName: realmName,
  expiration: 33200,
  conditions,
};

try {
  const res = await iamIdentityService.updateClaimRule(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

profile_claim_rule_conditions_model = {}
profile_claim_rule_conditions_model['claim'] = 'blueGroups'
profile_claim_rule_conditions_model['operator'] = 'EQUALS'
profile_claim_rule_conditions_model['value'] = '\"Europe_Group\"'
claimRule = iam_identity_service.update_claim_rule(
  profile_id=profile_id,
  rule_id=claimRule_id,
  if_match=claimRule_etag,
  expiration=33200,
  conditions=[profile_claim_rule_conditions_model],
  type='Profile-SAML',
  realm_name='https://sdk.test.realm/1234',
).get_result()
print(json.dumps(claimRule, indent=2))
Copy to clipboard

Response

Response Body

ProfileClaimRule

Status Code

200
Successful - Claim rule updated.
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.

Example responses

Status 200

{
  "id": "ClaimRule-faa0b1f4-d9e0-42f3-b61c-3927db1cef9b",
  "entity_tag": "1-cd52f1eaf1e7464f9ba30f37c5c5fe32",
  "created_at": "2021-07-28T10:23+0000",
  "modified_at": "2021-07-28T17:16+0000",
  "name": "My Claim rule updated",
  "type": "Profile-SAML",
  "realm_name": "https://www.example.org/my-nice-idp",
  "expiration": 2600,
  "conditions": {
    "claim": "groups",
    "operator": "CONTAINS",
    "value": "\"cloud-docs-dev\""
  }
}
Copy to clipboard

Success example

{
  "id": "ClaimRule-faa0b1f4-d9e0-42f3-b61c-3927db1cef9b",
  "entity_tag": "1-cd52f1eaf1e7464f9ba30f37c5c5fe32",
  "created_at": "2021-07-28T10:23+0000",
  "modified_at": "2021-07-28T17:16+0000",
  "name": "My Claim rule updated",
  "type": "Profile-SAML",
  "realm_name": "https://www.example.org/my-nice-idp",
  "expiration": 2600,
  "conditions": {
    "claim": "groups",
    "operator": "CONTAINS",
    "value": "\"cloud-docs-dev\""
  }
}
Copy to clipboard

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.

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

(iamIdentity *IamIdentityV1) DeleteClaimRule(deleteClaimRuleOptions *DeleteClaimRuleOptions) (response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) DeleteClaimRuleWithContext(ctx context.Context, deleteClaimRuleOptions *DeleteClaimRuleOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> deleteClaimRule(DeleteClaimRuleOptions deleteClaimRuleOptions)
Copy to clipboard

deleteClaimRule(params)

delete_claim_rule(
        self,
        profile_id: str,
        rule_id: str,
        **kwargs,
    ) -> DetailedResponse

Authorization

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

iam-identity.profile.update

Auditing

Calling this method generates the following auditing event.

iam-identity.profile.update

Request

Instantiate the DeleteClaimRuleOptions struct and set the fields to provide parameter values for the DeleteClaimRule method.

Use the DeleteClaimRuleOptions.Builder to create a DeleteClaimRuleOptions object that contains the parameter values for the deleteClaimRule method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

profile-id
Required*
string
ID of the trusted profile.
rule-id
Required*
string
ID of the claim rule to delete.

parameter

WithContext method only

DeleteClaimRuleOptions

The DeleteClaimRule options.

DeleteClaimRuleOptions

The deleteClaimRule options.

parameters

profileId
Required*
string
ID of the trusted profile.
ruleId
Required*
string
ID of the claim rule to delete.

parameters

profile_id
Required*
str
ID of the trusted profile.
rule_id
Required*
str
ID of the claim rule to delete.

Example request

curl -X DELETE "https://iam.cloud.ibm.com/v1/profiles/PROFILE_ID/rules/CLAIM_RULE_ID" --header "Authorization: Bearer $TOKEN"
Copy to clipboard

Example request

deleteClaimRuleOptions := iamIdentityService.NewDeleteClaimRuleOptions(profileId, claimRuleId)

response, err := iamIdentityService.DeleteClaimRule(deleteClaimRuleOptions)
if err != nil {
  panic(err)
}
Copy to clipboard

Example request

DeleteClaimRuleOptions deleteClaimRuleOptions = new DeleteClaimRuleOptions.Builder()
    .profileId(profileId)
    .ruleId(claimRuleId)
    .build();
Response<Void> response = service.deleteClaimRule(deleteClaimRuleOptions).execute();

Example request

const params = {
  profileId,
  ruleId: claimRuleId,
};

try {
  await iamIdentityService.deleteClaimRule(params);
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

response = iam_identity_service.delete_claim_rule(profile_id=profile_id, rule_id=claimRule_id)

Response

Status Code

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.

No Sample Response

This method does not specify any sample responses.

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.

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

(iamIdentity *IamIdentityV1) CreateLink(createLinkOptions *CreateLinkOptions) (result *ProfileLink, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) CreateLinkWithContext(ctx context.Context, createLinkOptions *CreateLinkOptions) (result *ProfileLink, response *core.DetailedResponse, err error)

ServiceCall<ProfileLink> createLink(CreateLinkOptions createLinkOptions)
Copy to clipboard

createLink(params)

create_link(
        self,
        profile_id: str,
        cr_type: str,
        link: 'CreateProfileLinkRequestLink',
        *,
        name: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

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

Auditing

Calling this method generates the following auditing event.

iam-identity.profile.update

Request

Instantiate the CreateLinkOptions struct and set the fields to provide parameter values for the CreateLink method.

Use the CreateLinkOptions.Builder to create a CreateLinkOptions object that contains the parameter values for the createLink method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

profile-id
Required*
string
ID of the trusted profile.

Request Body

Required*

CreateProfileLinkRequest

Request to create a Link to Trusted profile.

parameter

WithContext method only

CreateLinkOptions

The CreateLink options.

CreateLinkOptions

The createLink options.

parameters

profileId
Required*
string
ID of the trusted profile.
crType
Required*
string
The compute resource type. Valid values are VSI, IKS_SA, ROKS_SA.
link
Link details.
name
string
Optional name of the Link.

parameters

profile_id
Required*
str
ID of the trusted profile.
cr_type
Required*
str
The compute resource type. Valid values are VSI, IKS_SA, ROKS_SA.
link
Link details.
name
str
Optional name of the Link.

Example request

curl -X POST "https://iam.cloud.ibm.com/v1/profiles/PROFILE_ID/links" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" --header "Accept: application/json" --data '{
    "name": "my link",
    "cr_type": "VSI",
    "link": {
        "crn": "crn:v1:bluemix:public:iam-identity::a/18e3020749ce4744b0b472466d61fdb4::computeresource:Fake-Compute-Resource",
        "namespace": "default",
        "name": "my compute resource name"
     }
}'
Copy to clipboard

Example request

createProfileLinkRequestLink := new(iamidentityv1.CreateProfileLinkRequestLink)
createProfileLinkRequestLink.CRN = core.StringPtr("crn:v1:staging:public:iam-identity::a/" + accountID + "::computeresource:Fake-Compute-Resource")
createProfileLinkRequestLink.Namespace = core.StringPtr("default")
createProfileLinkRequestLink.Name = core.StringPtr("niceName")

createLinkOptions := iamIdentityService.NewCreateLinkOptions(profileId, "ROKS_SA", createProfileLinkRequestLink)
createLinkOptions.SetName("niceLink")

link, response, err := iamIdentityService.CreateLink(createLinkOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(link, "", "  ")
fmt.Println(string(b))
linkId = *link.ID
Copy to clipboard

Example request

CreateProfileLinkRequestLink link = new CreateProfileLinkRequestLink.Builder()
    .crn("crn:v1:staging:public:iam-identity::a/" + accountId + "::computeresource:Fake-Compute-Resource")
    .namespace("default")
    .name("nice name")
    .build();

CreateLinkOptions createLinkOptions = new CreateLinkOptions.Builder()
    .profileId(profileId)
    .name("Nice link")
    .crType("ROKS_SA")
    .link(link)
    .build();

Response<ProfileLink> response = service.createLink(createLinkOptions).execute();
ProfileLink linkResponse = response.getResult();
linkId = linkResponse.getId();

System.out.println(linkResponse);
Copy to clipboard

Example request

const CreateProfileLinkRequestLink = {
  crn: `crn:v1:staging:public:iam-identity::a/{accountId}::computeresource:Fake-Compute-Resource`,
  namespace: 'default',
  name: 'nice name',
};

const params = {
  profileId: profileId,
  name: 'nice link',
  crType: 'ROKS_SA',
  link: CreateProfileLinkRequestLink,
};

try {
  const res = await iamIdentityService.createLink(params)
  linkId = res.result.id
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

CreateProfileLinkRequestLink = {}
CreateProfileLinkRequestLink['crn'] = (
  'crn:v1:staging:public:iam-identity::a/' + account_id + '::computeresource:Fake-Compute-Resource'
)
CreateProfileLinkRequestLink['namespace'] = 'default'
CreateProfileLinkRequestLink['name'] = 'nice name'
link = iam_identity_service.create_link(
  profile_id=profile_id, name='nice link', cr_type='ROKS_SA', link=CreateProfileLinkRequestLink
).get_result()
print(json.dumps(link, indent=2))
Copy to clipboard

Response

Response Body

ProfileLink

Link details

ProfileLink

Link details.

ProfileLink

Link details.

ProfileLink

Link details.

ProfileLink

Link details.

Status Code

201
Link successfully created for trusted profile. Response if the Object could be created in the persistence layer.
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.

Example responses

Status 201

{
  "id": "ClaimRule-faa0b1f4-d9e0-42f3-b61c-3927db1cef9b",
  "entity_tag": "1-cd52f1eaf1e7464f9ba30f37c5c5fe32",
  "created_at": "2021-07-28T10:23+0000",
  "modified_at": "2021-07-28T10:23+0000",
  "name": "Link to Compute Resource",
  "cr_type": "VSI",
  "link": {
    "crn": "crn:v1:bluemix:public:iam-identity::a/18e3020749ce4744b0b472466d61fdb4::profile:ClaimRule-faa0b1f4-d9e0-42f3-b61c-3927db1cef9b",
    "namespace": "default",
    "name": "my compute resource name"
  }
}
Copy to clipboard

Success example

{
  "id": "ClaimRule-faa0b1f4-d9e0-42f3-b61c-3927db1cef9b",
  "entity_tag": "1-cd52f1eaf1e7464f9ba30f37c5c5fe32",
  "created_at": "2021-07-28T10:23+0000",
  "modified_at": "2021-07-28T10:23+0000",
  "name": "Link to Compute Resource",
  "cr_type": "VSI",
  "link": {
    "crn": "crn:v1:bluemix:public:iam-identity::a/18e3020749ce4744b0b472466d61fdb4::profile:ClaimRule-faa0b1f4-d9e0-42f3-b61c-3927db1cef9b",
    "namespace": "default",
    "name": "my compute resource name"
  }
}
Copy to clipboard

Get a list of links to a trusted profile.

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

(iamIdentity *IamIdentityV1) ListLinks(listLinksOptions *ListLinksOptions) (result *ProfileLinkList, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) ListLinksWithContext(ctx context.Context, listLinksOptions *ListLinksOptions) (result *ProfileLinkList, response *core.DetailedResponse, err error)

ServiceCall<ProfileLinkList> listLinks(ListLinksOptions listLinksOptions)
Copy to clipboard

listLinks(params)

list_links(
        self,
        profile_id: str,
        **kwargs,
    ) -> DetailedResponse

Authorization

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

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

Auditing

Calling this method generates the following auditing event.

iam-identity.profile.get

Request

Instantiate the ListLinksOptions struct and set the fields to provide parameter values for the ListLinks method.

Use the ListLinksOptions.Builder to create a ListLinksOptions object that contains the parameter values for the listLinks method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

profile-id
Required*
string
ID of the trusted profile

parameter

WithContext method only

ListLinksOptions

The ListLinks options.

ListLinksOptions

The listLinks options.

parameters

profileId
Required*
string
ID of the trusted profile.

parameters

profile_id
Required*
str
ID of the trusted profile.

Example request

curl -X GET "https://iam.cloud.ibm.com/v1/profiles/PROFILE_ID/links" --header "Authorization: Bearer $TOKEN" --header "Accept: application/json" 
Copy to clipboard

Example request

listLinksOptions := iamIdentityService.NewListLinksOptions(profileId)

linkList, response, err := iamIdentityService.ListLinks(listLinksOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(linkList, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

ListLinksOptions listLinksOptions = new ListLinksOptions.Builder()
    .profileId(profileId)
    .build();

Response<ProfileLinkList> response = service.listLinks(listLinksOptions).execute();
ProfileLinkList links = response.getResult();

System.out.println(links);

Example request

const params = {
  profileId,
};

try {
  const res = await iamIdentityService.listLinks(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

link_list = iam_identity_service.list_links(
  profile_id=profile_id,
).get_result()
print(json.dumps(link_list, indent=2))

Response

Response Body

ProfileLinkList

Status Code

200
Successful - Get list of link 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.

Example responses

Status 200

{
  "links": [
    {
      "id": "ClaimRule-faa0b1f4-d9e0-42f3-b61c-3927db1cef9b",
      "entity_tag": "1-cd52f1eaf1e7464f9ba30f37c5c5fe32",
      "created_at": "2021-07-28T10:23+0000",
      "modified_at": "2021-07-28T10:23+0000",
      "name": "Link to Compute Resource",
      "cr_type": "VSI",
      "link": {
        "crn": "crn:v1:bluemix:public:iam-identity::a/18e3020749ce4744b0b472466d61fdb4::profile:ClaimRule-faa0b1f4-d9e0-42f3-b61c-3927db1cef9b",
        "namespace": "default",
        "name": "my compute resource name"
      }
    }
  ]
}
Copy to clipboard

Success example

{
  "links": [
    {
      "id": "ClaimRule-faa0b1f4-d9e0-42f3-b61c-3927db1cef9b",
      "entity_tag": "1-cd52f1eaf1e7464f9ba30f37c5c5fe32",
      "created_at": "2021-07-28T10:23+0000",
      "modified_at": "2021-07-28T10:23+0000",
      "name": "Link to Compute Resource",
      "cr_type": "VSI",
      "link": {
        "crn": "crn:v1:bluemix:public:iam-identity::a/18e3020749ce4744b0b472466d61fdb4::profile:ClaimRule-faa0b1f4-d9e0-42f3-b61c-3927db1cef9b",
        "namespace": "default",
        "name": "my compute resource name"
      }
    }
  ]
}
Copy to clipboard

Get a specific link to a trusted profile by link_id.

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

(iamIdentity *IamIdentityV1) GetLink(getLinkOptions *GetLinkOptions) (result *ProfileLink, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) GetLinkWithContext(ctx context.Context, getLinkOptions *GetLinkOptions) (result *ProfileLink, response *core.DetailedResponse, err error)

ServiceCall<ProfileLink> getLink(GetLinkOptions getLinkOptions)
Copy to clipboard

getLink(params)

get_link(
        self,
        profile_id: str,
        link_id: str,
        **kwargs,
    ) -> DetailedResponse

Authorization

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

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

Auditing

Calling this method generates the following auditing event.

iam-identity.profile.get

Request

Instantiate the GetLinkOptions struct and set the fields to provide parameter values for the GetLink method.

Use the GetLinkOptions.Builder to create a GetLinkOptions object that contains the parameter values for the getLink method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

profile-id
Required*
string
ID of the trusted profile
link-id
Required*
string
ID of the link

parameter

WithContext method only

GetLinkOptions

The GetLink options.

GetLinkOptions

The getLink options.

parameters

profileId
Required*
string
ID of the trusted profile.
linkId
Required*
string
ID of the link.

parameters

profile_id
Required*
str
ID of the trusted profile.
link_id
Required*
str
ID of the link.

Example request

curl -X GET "https://iam.cloud.ibm.com/v1/profiles/PROFILE_ID/links/LINK_ID" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" 
Copy to clipboard

Example request

getLinkOptions := iamIdentityService.NewGetLinkOptions(profileId, linkId)

link, response, err := iamIdentityService.GetLink(getLinkOptions)
if err != nil {
  panic(err)
}
Copy to clipboard

Example request

GetLinkOptions getLinkOptions = new GetLinkOptions.Builder()
    .profileId(profileId)
    .linkId(linkId)
    .build();

Response<ProfileLink> response = service.getLink(getLinkOptions).execute();
ProfileLink link = response.getResult();

System.out.println(link);

Example request

const params = {
  profileId: profileId,
  linkId,
};

try {
  const res = await iamIdentityService.getLink(params)
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

response = iam_identity_service.get_link(profile_id=profile_id, link_id=link_id)
link = response.get_result()
print(json.dumps(link, indent=2))

Response

Response Body

ProfileLink

Link details

ProfileLink

Link details.

ProfileLink

Link details.

ProfileLink

Link details.

ProfileLink

Link details.

Status Code

200
Successful - Get of link 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
Link with provided ID not found.
500
Internal Server error.

Example responses

Status 200

{
  "id": "ClaimRule-faa0b1f4-d9e0-42f3-b61c-3927db1cef9b",
  "entity_tag": "1-cd52f1eaf1e7464f9ba30f37c5c5fe32",
  "created_at": "2021-07-28T10:23+0000",
  "modified_at": "2021-07-28T10:23+0000",
  "name": "Link to Compute Resource",
  "cr_type": "VSI",
  "link": {
    "crn": "crn:v1:bluemix:public:iam-identity::a/18e3020749ce4744b0b472466d61fdb4::profile:ClaimRule-faa0b1f4-d9e0-42f3-b61c-3927db1cef9b",
    "namespace": "default",
    "name": "my compute resource name"
  }
}
Copy to clipboard

Success example

{
  "id": "ClaimRule-faa0b1f4-d9e0-42f3-b61c-3927db1cef9b",
  "entity_tag": "1-cd52f1eaf1e7464f9ba30f37c5c5fe32",
  "created_at": "2021-07-28T10:23+0000",
  "modified_at": "2021-07-28T10:23+0000",
  "name": "Link to Compute Resource",
  "cr_type": "VSI",
  "link": {
    "crn": "crn:v1:bluemix:public:iam-identity::a/18e3020749ce4744b0b472466d61fdb4::profile:ClaimRule-faa0b1f4-d9e0-42f3-b61c-3927db1cef9b",
    "namespace": "default",
    "name": "my compute resource name"
  }
}
Copy to clipboard

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

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

(iamIdentity *IamIdentityV1) DeleteLink(deleteLinkOptions *DeleteLinkOptions) (response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) DeleteLinkWithContext(ctx context.Context, deleteLinkOptions *DeleteLinkOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> deleteLink(DeleteLinkOptions deleteLinkOptions)
Copy to clipboard

deleteLink(params)

delete_link(
        self,
        profile_id: str,
        link_id: str,
        **kwargs,
    ) -> DetailedResponse

Authorization

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

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

Auditing

Calling this method generates the following auditing event.

iam-identity.profile.update

Request

Instantiate the DeleteLinkOptions struct and set the fields to provide parameter values for the DeleteLink method.

Use the DeleteLinkOptions.Builder to create a DeleteLinkOptions object that contains the parameter values for the deleteLink method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

profile-id
Required*
string
ID of the trusted profile
link-id
Required*
string
ID of the link

parameter

WithContext method only

DeleteLinkOptions

The DeleteLink options.

DeleteLinkOptions

The deleteLink options.

parameters

profileId
Required*
string
ID of the trusted profile.
linkId
Required*
string
ID of the link.

parameters

profile_id
Required*
str
ID of the trusted profile.
link_id
Required*
str
ID of the link.

Example request

curl -X DELETE "https://iam.cloud.ibm.com/v1/profiles/PROFILE_ID/links/LINKS_ID" --header "Authorization: Bearer $TOKEN"
Copy to clipboard

Example request

deleteLinkOptions := iamIdentityService.NewDeleteLinkOptions(profileId, linkId)

response, err := iamIdentityService.DeleteLink(deleteLinkOptions)
if err != nil {
  panic(err)
}
Copy to clipboard

Example request

DeleteLinkOptions deleteLinkOptions = new DeleteLinkOptions.Builder()
    .profileId(profileId)
    .linkId(linkId)
    .build();
Response<Void> response = service.deleteLink(deleteLinkOptions).execute();

Example request

const params = {
  profileId,
  linkId,
};

try {
  await iamIdentityService.deleteLink(params);
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

response = iam_identity_service.delete_link(profile_id=profile_id, link_id=link_id)

Response

Status Code

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.

No Sample Response

This method does not specify any sample responses.

Get a list of identities that can assume the trusted profile

Get a list of identities that can assume the trusted profile.

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

(iamIdentity *IamIdentityV1) GetProfileIdentities(getProfileIdentitiesOptions *GetProfileIdentitiesOptions) (result *ProfileIdentitiesResponse, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) GetProfileIdentitiesWithContext(ctx context.Context, getProfileIdentitiesOptions *GetProfileIdentitiesOptions) (result *ProfileIdentitiesResponse, response *core.DetailedResponse, err error)

ServiceCall<ProfileIdentitiesResponse> getProfileIdentities(GetProfileIdentitiesOptions getProfileIdentitiesOptions)
Copy to clipboard

getProfileIdentities(params)

get_profile_identities(
        self,
        profile_id: str,
        **kwargs,
    ) -> DetailedResponse

Authorization

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

iam-identity.profile.get

Auditing

Calling this method generates the following auditing event.

iam-identity.profile.get

Request

Instantiate the GetProfileIdentitiesOptions struct and set the fields to provide parameter values for the GetProfileIdentities method.

Use the GetProfileIdentitiesOptions.Builder to create a GetProfileIdentitiesOptions object that contains the parameter values for the getProfileIdentities method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

profile-id
Required*
string
ID of the trusted profile.

parameter

WithContext method only

GetProfileIdentitiesOptions

The GetProfileIdentities options.

GetProfileIdentitiesOptions

The getProfileIdentities options.

parameters

profileId
Required*
string
ID of the trusted profile.

parameters

profile_id
Required*
str
ID of the trusted profile.

Example request

curl -X GET "https://iam.cloud.ibm.com/v1/profiles/PROFILE_ID/identities" --header "Authorization: Bearer $TOKEN" --header "Accept: application/json" 
Copy to clipboard

Example request

getProfileIdentitiesOptions := iamidentityv1.GetProfileIdentitiesOptions{
  ProfileID: &profileId,
}

profileIdentities, response, err := iamIdentityService.GetProfileIdentities(&getProfileIdentitiesOptions)

if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(profileIdentities, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

GetProfileIdentitiesOptions getProfileIdentitiesOptions = new GetProfileIdentitiesOptions.Builder()
    .profileId(profileId).build();
Response<ProfileIdentitiesResponse> response = service.getProfileIdentities(getProfileIdentitiesOptions)
    .execute();

ProfileIdentitiesResponse profileIdentityResponseResult = response.getResult();
profileIdentitiesEtag = profileIdentityResponseResult.getEntityTag();

Example request

const params = {
  profileId,
};

try {
  const res = await iamIdentityService.getProfileIdentities(params);
  const { result } = res;
  profileIdentitiesEtag = result.entity_tag;
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

response = iam_identity_service.get_profile_identities(profile_id=profile_id)

Response

Response Body

ProfileIdentitiesResponse

Status Code

200
Successful response with 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.

Example responses

Status 200

{
  "entity_tag": "1-cd52f1eaf1e7464f9ba30f37c5c5fe32",
  "identities": [
    {
      "iam_id": "IBMid-1234567898",
      "identifier": "IBMid-1234567898",
      "type": "user",
      "name": "user@ibm.com",
      "email": "user@ibm.com",
      "accounts": "account in the token",
      "description": "description"
    },
    {
      "iam_id": "iam-ServiceId-ee1103f8-e03b-4d02-a977-e540ebdffb16",
      "identifier": "ServiceId-ee1103f8-e03b-4d02-a977-e540ebdffb16",
      "type": "serviceid"
    },
    {
      "iam_id": "crn-crn:v1:bluemix:public:cloudantnosqldb:us-south:a/36d797c19715462e8a0eaeacefe82f8b:4adba58a-c3f7-4c37-b904-bc965e6d562a::",
      "identifier": "crn:v1:bluemix:public:cloudantnosqldb:us-south:a/36d797c19715462e8a0eaeacefe82f8b:4adba58a-c3f7-4c37-b904-bc965e6d562a::",
      "type": "crn",
      "description": "cloudant database shared with profile"
    }
  ]
}
Copy to clipboard

Success example

{
  "entity_tag": "1-cd52f1eaf1e7464f9ba30f37c5c5fe32",
  "identities": [
    {
      "iam_id": "IBMid-1234567898",
      "identifier": "IBMid-1234567898",
      "type": "user",
      "name": "user@ibm.com",
      "email": "user@ibm.com",
      "accounts": "account in the token",
      "description": "description"
    },
    {
      "iam_id": "iam-ServiceId-ee1103f8-e03b-4d02-a977-e540ebdffb16",
      "identifier": "ServiceId-ee1103f8-e03b-4d02-a977-e540ebdffb16",
      "type": "serviceid"
    },
    {
      "iam_id": "crn-crn:v1:bluemix:public:cloudantnosqldb:us-south:a/36d797c19715462e8a0eaeacefe82f8b:4adba58a-c3f7-4c37-b904-bc965e6d562a::",
      "identifier": "crn:v1:bluemix:public:cloudantnosqldb:us-south:a/36d797c19715462e8a0eaeacefe82f8b:4adba58a-c3f7-4c37-b904-bc965e6d562a::",
      "type": "crn",
      "description": "cloudant database shared with profile"
    }
  ]
}
Copy to clipboard

Update the list of identities that can assume the trusted profile

Update the list of identities that can assume the trusted profile.

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

(iamIdentity *IamIdentityV1) SetProfileIdentities(setProfileIdentitiesOptions *SetProfileIdentitiesOptions) (result *ProfileIdentitiesResponse, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) SetProfileIdentitiesWithContext(ctx context.Context, setProfileIdentitiesOptions *SetProfileIdentitiesOptions) (result *ProfileIdentitiesResponse, response *core.DetailedResponse, err error)

ServiceCall<ProfileIdentitiesResponse> setProfileIdentities(SetProfileIdentitiesOptions setProfileIdentitiesOptions)
Copy to clipboard

setProfileIdentities(params)

set_profile_identities(
        self,
        profile_id: str,
        if_match: str,
        *,
        identities: Optional[List['ProfileIdentityRequest']] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.profile.update

Auditing

Calling this method generates the following auditing event.

iam-identity.profile.update

Request

Instantiate the SetProfileIdentitiesOptions struct and set the fields to provide parameter values for the SetProfileIdentities method.

Use the SetProfileIdentitiesOptions.Builder to create a SetProfileIdentitiesOptions object that contains the parameter values for the setProfileIdentities method.

Custom Headers

If-Match
Required*
string
Entity tag of the Identities to be updated. Specify the tag that you retrieved when reading the Profile Identities. This value helps identify parallel usage of this API. Pass * to indicate updating any available version, which may result in stale updates.
Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

profile-id
Required*
string
ID of the trusted profile.

Request Body

Required*

ProfileIdentitiesUpdateRequest

Request to update identities.

parameter

WithContext method only

SetProfileIdentitiesOptions

The SetProfileIdentities options.

SetProfileIdentitiesOptions

The setProfileIdentities options.

parameters

profileId
Required*
string
ID of the trusted profile.
ifMatch
Required*
string
Entity tag of the Identities to be updated. Specify the tag that you retrieved when reading the Profile Identities. This value helps identify parallel usage of this API. Pass * to indicate updating any available version, which may result in stale updates.
identities
List of identities that can assume the trusted profile.

parameters

profile_id
Required*
str
ID of the trusted profile.
if_match
Required*
str
Entity tag of the Identities to be updated. Specify the tag that you retrieved when reading the Profile Identities. This value helps identify parallel usage of this API. Pass * to indicate updating any available version, which may result in stale updates.
identities
List of identities that can assume the trusted profile.

Example request

curl -X PUT "https://iam.cloud.ibm.com/v1/profiles/PROFILE_ID/identities" --header "Authorization: Bearer $TOKEN" --header "If-Match: <value of etag header from GET request>" --header "Content-Type: application/json" --header "Accept: application/json" --data '{
    "identities": [
        {
            "iam_id": "IBMid-665002HHL3",
            "identifier": "IBMid-665002HHL3
            "type": "user",
            "description": "member of main account"
            "accounts": ["36d797c19715462e8a0eaeacefe82f8b"]
        }
    ]
}'
Copy to clipboard

Example request

accounts := []string{accountID}
identity := &iamidentityv1.ProfileIdentityRequest{
  Identifier:  &iamID,
  Accounts:    accounts,
  Type:        core.StringPtr("user"),
  Description: core.StringPtr("Identity description"),
}
listProfileIdentity := []iamidentityv1.ProfileIdentityRequest{*identity}
setProfileIdentitiesOptions := iamidentityv1.SetProfileIdentitiesOptions{
  ProfileID:  &profileId,
  Identities: listProfileIdentity,
  IfMatch:    &profileEtag,
}

profileIdnetities, response, err := iamIdentityService.SetProfileIdentities(&setProfileIdentitiesOptions)

if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(profileIdnetities, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

List<String> accounts = new ArrayList<String>();
accounts.add(accountId);
String type = "user";
String description = "Identity description";
ProfileIdentityRequest profileIdentity = new ProfileIdentityRequest.Builder()
    .identifier(iamId)
    .accounts(accounts)
    .type(type)
    .description(description)
    .build();
List<ProfileIdentityRequest> listProfileIdentity = new ArrayList<ProfileIdentityRequest>();
listProfileIdentity.add(profileIdentity);

SetProfileIdentitiesOptions setProfileIdentitiesOptions = new SetProfileIdentitiesOptions.Builder()
    .profileId(profileId)
    .identities(listProfileIdentity)
    .ifMatch(profileIdentitiesEtag)
    .build();

Response<ProfileIdentitiesResponse> response = service.setProfileIdentities(setProfileIdentitiesOptions)
    .execute();
ProfileIdentitiesResponse profileIdentitiesResponseResult = response.getResult();
Copy to clipboard

Example request

const profileaccounts=[accountId];
const ProfileIdentity= {
  identifier: iamId,
  type: 'user',
  accounts: profileaccounts,
  description: 'identity description'
}
const profileIdentities= [ProfileIdentity]
const params = {
  profileId: profileId,
  identities: profileIdentities,
  ifMatch: profileIdentitiesEtag
};

try {
  const res = await iamIdentityService.setProfileIdentities(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

accounts = [account_id]
profileIdentity = ProfileIdentityRequest(
  identifier=iam_id, accounts=accounts, type="user", description="Identity description"
)
profile_identities_input = [profileIdentity]
response = iam_identity_service.set_profile_identities(
  profile_id=profile_id, if_match=profile_identity_etag, identities=profile_identities_input
)
Copy to clipboard

Response

Response Body

ProfileIdentitiesResponse

Status Code

200
Successful response with 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.

Example responses

Status 200

{
  "entity_tag": "1-cd52f1eaf1e7464f9ba30f37c5c5fe32",
  "identities": [
    {
      "iam_id": "IBMid-12345678",
      "identifier": "IBMid-12345678",
      "type": "user",
      "accounts": "BSS_account_id in token",
      "description": "description"
    }
  ]
}
Copy to clipboard

Success example

{
  "entity_tag": "1-cd52f1eaf1e7464f9ba30f37c5c5fe32",
  "identities": [
    {
      "iam_id": "IBMid-12345678",
      "identifier": "IBMid-12345678",
      "type": "user",
      "accounts": "BSS_account_id in token",
      "description": "description"
    }
  ]
}
Copy to clipboard

Add a specific identity that can assume the trusted profile

Add a specific identity that can assume the trusted profile.

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

(iamIdentity *IamIdentityV1) SetProfileIdentity(setProfileIdentityOptions *SetProfileIdentityOptions) (result *ProfileIdentityResponse, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) SetProfileIdentityWithContext(ctx context.Context, setProfileIdentityOptions *SetProfileIdentityOptions) (result *ProfileIdentityResponse, response *core.DetailedResponse, err error)

ServiceCall<ProfileIdentityResponse> setProfileIdentity(SetProfileIdentityOptions setProfileIdentityOptions)
Copy to clipboard

setProfileIdentity(params)

set_profile_identity(
        self,
        profile_id: str,
        identity_type: str,
        identifier: str,
        type: str,
        *,
        accounts: Optional[List[str]] = None,
        description: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.profile.update

Auditing

Calling this method generates the following auditing event.

iam-identity.profile.update

Request

Instantiate the SetProfileIdentityOptions struct and set the fields to provide parameter values for the SetProfileIdentity method.

Use the SetProfileIdentityOptions.Builder to create a SetProfileIdentityOptions object that contains the parameter values for the setProfileIdentity method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

profile-id
Required*
string
ID of the trusted profile
identity-type
Required*
string
Type of the identity

Allowable values: [user,serviceid,crn]

Request Body

Required*

ProfileIdentityRequest

Request to update identities.

parameter

WithContext method only

SetProfileIdentityOptions

The SetProfileIdentity options.

SetProfileIdentityOptions

The setProfileIdentity options.

parameters

profileId
Required*
string
ID of the trusted profile.
identityType
Required*
string
Type of the identity.

Allowable values: [user,serviceid,crn]
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.

Allowable values: [user,serviceid,crn]
accounts
string[]
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'.

parameters

profile_id
Required*
str
ID of the trusted profile.
identity_type
Required*
str
Type of the identity.

Allowable values: [user,serviceid,crn]
identifier
Required*
str
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*
str
Type of the identity.

Allowable values: [user,serviceid,crn]
accounts
List[str]
Only valid for the type user. Accounts from which a user can assume the trusted profile.
description
str
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'.

Example request

curl -X POST "https://iam.cloud.ibm.com/v1/profiles/PROFILE_ID/identities/IDENTITY_TYPE" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" --header "Accept: application/json" --data '{
    "iam_id": "IBMid-665002HHL3",
    "identifier": "IBMid-665002HHL3",
    "type": "user",
    "description": "member of main account",
    "accounts": ["36d797c19715462e8a0eaeacefe82f8b"]
}'
Copy to clipboard

Example request

accounts := []string{accountID}
setProfileIdentityOptions := iamidentityv1.SetProfileIdentityOptions{
  ProfileID:    &profileId,
  IdentityType: core.StringPtr("user"),
  Identifier:   &iamIDMember,
  Accounts:     accounts,
  Type:         core.StringPtr("user"),
  Description:  core.StringPtr("Identity description"),
}

profileIdnetity, response, err := iamIdentityService.SetProfileIdentity(&setProfileIdentityOptions)

if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(profileIdnetity, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

List<String> accounts = new ArrayList<String>();
accounts.add(accountId);
String type = "user";
String description = "Identity description";

SetProfileIdentityOptions setProfileIdentityOptions = new SetProfileIdentityOptions.Builder()
    .profileId(profileId)
    .identityType(type)
    .identifier(iamIdMember)
    .type("user")
    .accounts(accounts)
    .description(description)
    .build();
Response<ProfileIdentityResponse> response = service.setProfileIdentity(setProfileIdentityOptions).execute();

ProfileIdentityResponse profileIdentityResponseResult = response.getResult();
System.out.println(profileIdentityResponseResult);
Copy to clipboard

Example request

const profileaccounts=[accountId];
const params = {
  profileId: profileId,
  identityType: 'user',
  identifier: iamIdMember,
  type: 'user',
  accounts: profileaccounts,
  description: 'identity description'
};

try {
  const res = await iamIdentityService.setProfileIdentity(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

accounts = [account_id]
response = iam_identity_service.set_profile_identity(
  profile_id=profile_id,
  identity_type="user",
  identifier=iam_id_member,
  type="user",
  accounts=accounts,
  description="Identity description",
)
Copy to clipboard

Response

Response Body

ProfileIdentityResponse

Status Code

200
Successful response with 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.

Example responses

Status 200

{
  "entity_tag": "1-cd52f1eaf1e7464f9ba30f37c5c5fe32",
  "identities": [
    {
      "iam_id": "IBMid-12345678",
      "identifier": "IBMid-12345678",
      "type": "user",
      "accounts": [
        "BSS_account_id"
      ],
      "description": "description"
    }
  ]
}
Copy to clipboard

Success example

{
  "entity_tag": "1-cd52f1eaf1e7464f9ba30f37c5c5fe32",
  "identities": [
    {
      "iam_id": "IBMid-12345678",
      "identifier": "IBMid-12345678",
      "type": "user",
      "accounts": [
        "BSS_account_id"
      ],
      "description": "description"
    }
  ]
}
Copy to clipboard

Get the identity that can assume the trusted profile

Get the identity that can assume the trusted profile.

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

(iamIdentity *IamIdentityV1) GetProfileIdentity(getProfileIdentityOptions *GetProfileIdentityOptions) (result *ProfileIdentityResponse, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) GetProfileIdentityWithContext(ctx context.Context, getProfileIdentityOptions *GetProfileIdentityOptions) (result *ProfileIdentityResponse, response *core.DetailedResponse, err error)

ServiceCall<ProfileIdentityResponse> getProfileIdentity(GetProfileIdentityOptions getProfileIdentityOptions)
Copy to clipboard

getProfileIdentity(params)

get_profile_identity(
        self,
        profile_id: str,
        identity_type: str,
        identifier_id: str,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.profile.get

Auditing

Calling this method generates the following auditing event.

iam-identity.profile.get

Request

Instantiate the GetProfileIdentityOptions struct and set the fields to provide parameter values for the GetProfileIdentity method.

Use the GetProfileIdentityOptions.Builder to create a GetProfileIdentityOptions object that contains the parameter values for the getProfileIdentity method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

profile-id
Required*
string
ID of the trusted profile
identity-type
Required*
string
Type of the identity

Allowable values: [user,serviceid,crn]
identifier-id
Required*
string
Identifier of the identity that can assume the trusted profiles.

parameter

WithContext method only

GetProfileIdentityOptions

The GetProfileIdentity options.

GetProfileIdentityOptions

The getProfileIdentity options.

parameters

profileId
Required*
string
ID of the trusted profile.
identityType
Required*
string
Type of the identity.

Allowable values: [user,serviceid,crn]
identifierId
Required*
string
Identifier of the identity that can assume the trusted profiles.

parameters

profile_id
Required*
str
ID of the trusted profile.
identity_type
Required*
str
Type of the identity.

Allowable values: [user,serviceid,crn]
identifier_id
Required*
str
Identifier of the identity that can assume the trusted profiles.

Example request

curl -X GET "https://iam.cloud.ibm.com/v1/profiles/PROFILE_ID/identities/IDENTITY_TYPE/IDENTIFIER_ID" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" --header "Accept: application/json" 
Copy to clipboard

Example request

getProfileIdentityOptions := iamidentityv1.GetProfileIdentityOptions{
  ProfileID:    &profileId,
  IdentityType: core.StringPtr("user"),
  IdentifierID: &iamIDMember,
}

profileIdnetity, response, err := iamIdentityService.GetProfileIdentity(&getProfileIdentityOptions)

if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(profileIdnetity, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

GetProfileIdentityOptions getProfileIdentityOptions = new GetProfileIdentityOptions.Builder()
    .profileId(profileId)
    .identityType("user")
    .identifierId(iamIdMember)
    .build();
Response<ProfileIdentityResponse> response = service.getProfileIdentity(getProfileIdentityOptions).execute();

ProfileIdentityResponse profileIdentityResponseResult = response.getResult();
System.out.println(profileIdentityResponseResult);

Example request

const params = {
  profileId: profileId,
  identityType: 'user',
  identifierId: iamId
};

try {
  const res = await iamIdentityService.getProfileIdentity(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

response = iam_identity_service.get_profile_identity(
  profile_id=profile_id, identity_type="user", identifier_id=iam_id_member
)

Response

Response Body

ProfileIdentityResponse

Status Code

200
Successful response with 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.

Example responses

Status 200

{
  "iam_id": "IBMid-12345678",
  "identifier": "IBMid-12345678",
  "type": "user",
  "accounts": [
    "BSS_account_id"
  ],
  "description": "description"
}
Copy to clipboard

Success example

{
  "iam_id": "IBMid-12345678",
  "identifier": "IBMid-12345678",
  "type": "user",
  "accounts": [
    "BSS_account_id"
  ],
  "description": "description"
}
Copy to clipboard

Delete the identity that can assume the trusted profile

Delete the identity that can assume the trusted profile.

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

(iamIdentity *IamIdentityV1) DeleteProfileIdentity(deleteProfileIdentityOptions *DeleteProfileIdentityOptions) (response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) DeleteProfileIdentityWithContext(ctx context.Context, deleteProfileIdentityOptions *DeleteProfileIdentityOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> deleteProfileIdentity(DeleteProfileIdentityOptions deleteProfileIdentityOptions)
Copy to clipboard

deleteProfileIdentity(params)

delete_profile_identity(
        self,
        profile_id: str,
        identity_type: str,
        identifier_id: str,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.profile.update

Auditing

Calling this method generates the following auditing event.

iam-identity.profile.update

Request

Instantiate the DeleteProfileIdentityOptions struct and set the fields to provide parameter values for the DeleteProfileIdentity method.

Use the DeleteProfileIdentityOptions.Builder to create a DeleteProfileIdentityOptions object that contains the parameter values for the deleteProfileIdentity method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

profile-id
Required*
string
ID of the trusted profile
identity-type
Required*
string
Type of the identity

Allowable values: [user,serviceid,crn]
identifier-id
Required*
string
Identifier of the identity that can assume the trusted profiles.

parameter

WithContext method only

DeleteProfileIdentityOptions

The DeleteProfileIdentity options.

DeleteProfileIdentityOptions

The deleteProfileIdentity options.

parameters

profileId
Required*
string
ID of the trusted profile.
identityType
Required*
string
Type of the identity.

Allowable values: [user,serviceid,crn]
identifierId
Required*
string
Identifier of the identity that can assume the trusted profiles.

parameters

profile_id
Required*
str
ID of the trusted profile.
identity_type
Required*
str
Type of the identity.

Allowable values: [user,serviceid,crn]
identifier_id
Required*
str
Identifier of the identity that can assume the trusted profiles.

Example request

curl -X DELETE "https://iam.cloud.ibm.com/v1/profiles/PROFILE_ID/identities/IDENTITY_TYPE/IDENTIFIER_ID" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" --header "Accept: application/json" 
Copy to clipboard

Example request

deleteProfileIdentityOptions := iamidentityv1.DeleteProfileIdentityOptions{
  ProfileID:    &profileId,
  IdentityType: core.StringPtr("user"),
  IdentifierID: &iamIDMember,
}

response, err := iamIdentityService.DeleteProfileIdentity(&deleteProfileIdentityOptions)

if err != nil {
  panic(err)
}
Copy to clipboard

Example request

DeleteProfileIdentityOptions deleteProfileIdentityOptions = new DeleteProfileIdentityOptions.Builder()
    .profileId(profileId)
    .identityType("user")
    .identifierId(iamIdMember)
    .build();
Response<Void> response = service.deleteProfileIdentity(deleteProfileIdentityOptions).execute();

Void profileIdentityResponseResult = response.getResult();
System.out.println(profileIdentityResponseResult);

Example request

const params = {
  profileId: profileId,
  identityType: 'user',
  identifierId: iamIdMember
};

try {
  const res = await iamIdentityService.deleteProfileIdentity(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

response = iam_identity_service.delete_profile_identity(
  profile_id=profile_id, identity_type="user", identifier_id=iam_id_member
)

Response

Status Code

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.
500
Internal Server error.

No Sample Response

This method does not specify any sample responses.

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

POST /identity/token#apikey

Auditing

Calling this method generates the following auditing events.

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

Request

Custom Headers

ibm-cloud-tenant
string
A comma separated list of enterprise ids and/or account ids. If present, an IAM token for the API key can only be created if the account id or enterprise id of the API key is contained in this header.

Form Parameters

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.

Example request

curl -X POST "https://iam.cloud.ibm.com/identity/token" --header "Content-Type: application/x-www-form-urlencoded" --data 'grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=$MY_APIKEY'
Copy to clipboard

Response

Response Body

token-response

Response body for POST /identity/token.

Status Code

200
Successful operation.
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.

Example responses

Status 200

{
  "access_token": "ACCESS_TOKEN",
  "refresh_token": "not_supported",
  "token_type": "bearer",
  "expires_in": 3600,
  "expiration": 1616750582
}
Copy to clipboard

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.

POST /identity/token#password

Auditing

Calling this method generates the following auditing event.

An event is generated only when an account is provided.

iam-identity.user-password.login

Request

Custom Headers

Authorization
Required*
string
Basic Authorization Header containing a valid client ID and secret. If this header is omitted the request fails with BXNIM0308E: 'No authorization header found'. You can use the client ID and secret that is used by the IBM Cloud CLI: bx / bx
ibm-cloud-tenant
string
A comma separated list of enterprise ids and/or account ids. If present, an IAM token for the username / password / account combination can only be created if the account id matches the passed account or the account is member of the enterprise id in this header.

Form Parameters

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.

Example request

curl -X POST \-u 'bx:bx' "https://iam.cloud.ibm.com/identity/token" --header "Content-Type: application/x-www-form-urlencoded" --data 'grant_type=password&username=$USERNAME&password=$PASSWORD&account=$ACCOUNT_IDENTIFIER'
Copy to clipboard

Response

Response Body

token-response

Response body for POST /identity/token.

Status Code

200
Successful operation.
400
Parameter validation failed. Response if required parameters are missing or if parameter values are invalid.
401
The incoming request did not contain valid authentication information.
403
The incoming request did not contain valid authentication information.
500
Internal server error. Response if unexpected error situation happened.

Example responses

Status 200

{
  "access_token": "ACCESS_TOKEN",
  "refresh_token": "not_supported",
  "token_type": "bearer",
  "expires_in": 3600,
  "expiration": 1616750582
}
Copy to clipboard

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.

POST /identity/token#iam-authz

Request

Form Parameters

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

Example request

curl -X POST "https://iam.cloud.ibm.com/identity/token" --header "Content-Type: application/x-www-form-urlencoded" --data 'grant_type=urn:ibm:params:oauth:grant-type:iam-authz&access_token=...&desired_iam_id=crn-crn:v1:bluemix:public:cloud-object-storage:global:a/59bcbfa6ea2f006b4ed7094c1a08dcdd:1a0ec336-f391-4091-a6fb-5e084a4c56f4::'
Copy to clipboard

Response

Response Body

token-response

Response body for POST /identity/token.

Status Code

200
Successful operation.
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.

Example responses

Status 200

{
  "access_token": "ACCESS_TOKEN",
  "refresh_token": "not_supported",
  "token_type": "bearer",
  "expires_in": 3600,
  "expiration": 1616750582
}
Copy to clipboard

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

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

Auditing

Calling this method generates the following auditing event.

iam-identity.user-apikey.login

Request

Custom Headers

ibm-cloud-tenant
string
A comma separated list of enterprise ids and/or account ids. If present, an IAM token for the API key can only be created if the account id or enterprise id of the API key is contained in this header.

Form Parameters

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.

Example request

curl -X POST "https://iam.cloud.ibm.com/identity/token" --header "Content-Type: application/x-www-form-urlencoded" --data 'grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=$MY_APIKEY&response_type=cloud_iam+delegated_refresh_token&receiver_client_ids=RECEIVER_CLIENTS&delegated_refresh_token_expiry=300'
Copy to clipboard

Response

Response Body

token-response

Response body for POST /identity/token.

Status Code

200
Successful operation.
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.

Example responses

Status 200

{
  "access_token": "ACCESS_TOKEN",
  "refresh_token": "not_supported",
  "delegated_refresh_token": "DELEGATED_REFRESH_TOKEN",
  "token_type": "bearer",
  "expires_in": 3600,
  "expiration": 1616750582
}
Copy to clipboard

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

POST /identity/token#cr-token

Auditing

Calling this method generates the following auditing event.

iam-identity.computeresource-token.login

Request

Custom Headers

Authorization
string
IBM Services can pass in a Basic Authorization Header representing a client id with a secret. For customers, omit this header parameter. To build a valid Basic Authorization Header, concatenate the client id with a colon and the secret, i.e. client_id:client_secret. This sequence must be Base64 encoded, and prefixed with Basic, so that a valid Basic Authorization Header would be: Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=
ibm-cloud-tenant
string
A comma separated list of enterprise ids and/or account ids. If present, an IAM token for the Trusted Profile can only be created if the Trusted Profile is part of one of the account ids or enterprise ids provided in this header.

Form Parameters

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'

Example request

curl -X POST "https://iam.cloud.ibm.com/identity/token" --header "Content-Type: application/x-www-form-urlencoded" --header "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ="  --data-urlencode 'grant_type=urn:ibm:params:oauth:grant-type:cr-token'  --data-urlencode 'cr_token=CR-TOKEN'  --data-urlencode 'profile_name=My first profile'
Copy to clipboard

Response

Response Body

token-response

Response body for POST /identity/token.

Status Code

200
Successful operation.
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.

Example responses

Status 200

{
  "access_token": "ACCESS_TOKEN",
  "refresh_token": "",
  "token_type": "bearer",
  "expires_in": 3600,
  "expiration": 1616750582
}
Copy to clipboard

Creates a non-opaque access token for a profile.

POST /identity/token#assume

Auditing

Calling this method generates the following auditing event.

iam-identity.assume-profile.login

Request

Form Parameters

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

Example request

curl -X POST "https://iam.cloud.ibm.com/identity/token" --header "Content-Type: application/x-www-form-urlencoded"  --data-urlencode 'grant_type=urn:ibm:params:oauth:grant-type:assume'  --data-urlencode 'access_token=ACCESS-TOKEN'  --data-urlencode 'profile_name=My first profile'
Copy to clipboard

Response

Response Body

token-response

Response body for POST /identity/token.

Status Code

200
Successful operation.
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.

Example responses

Status 200

{
  "access_token": "ACCESS_TOKEN",
  "refresh_token": "REFRESH_TOKEN",
  "token_type": "bearer",
  "expires_in": 3600,
  "expiration": 1616750582
}
Copy to clipboard

Returns the details of an account's configuration.

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

(iamIdentity *IamIdentityV1) GetAccountSettings(getAccountSettingsOptions *GetAccountSettingsOptions) (result *AccountSettingsResponse, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) GetAccountSettingsWithContext(ctx context.Context, getAccountSettingsOptions *GetAccountSettingsOptions) (result *AccountSettingsResponse, response *core.DetailedResponse, err error)

ServiceCall<AccountSettingsResponse> getAccountSettings(GetAccountSettingsOptions getAccountSettingsOptions)
Copy to clipboard

getAccountSettings(params)

get_account_settings(
        self,
        account_id: str,
        *,
        include_history: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.account.get

Request

Instantiate the GetAccountSettingsOptions struct and set the fields to provide parameter values for the GetAccountSettings method.

Use the GetAccountSettingsOptions.Builder to create a GetAccountSettingsOptions object that contains the parameter values for the getAccountSettings method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the 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.

Default: false

parameter

WithContext method only

GetAccountSettingsOptions

The GetAccountSettings options.

GetAccountSettingsOptions

The getAccountSettings options.

parameters

accountId
Required*
string
Unique ID of the account.
includeHistory
boolean
Defines if the entity history is included in the response.

Default: false

parameters

account_id
Required*
str
Unique ID of the account.
include_history
bool
Defines if the entity history is included in the response.

Default: false

Example request

curl -X GET "https://iam.cloud.ibm.com/v1/accounts/ACCOUNT_ID/settings/identity" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" 
Copy to clipboard

Example request

getAccountSettingsOptions := iamIdentityService.NewGetAccountSettingsOptions(accountID)

accountSettingsResponse, response, err := iamIdentityService.GetAccountSettings(getAccountSettingsOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(accountSettingsResponse, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

GetAccountSettingsOptions getAccountSettingsOptions = new GetAccountSettingsOptions.Builder()
    .accountId(accountId)
    .build();

Response<AccountSettingsResponse> response = service.getAccountSettings(getAccountSettingsOptions).execute();
AccountSettingsResponse accountSettingsResponse = response.getResult();

accountSettingsEtag = response.getHeaders().values("Etag").get(0);

System.out.println(accountSettingsResponse);
Copy to clipboard

Example request

const params = {
  accountId: accountId,
};

try {
  const res = await iamIdentityService.getAccountSettings(params);
  accountSettingsEtag = res.headers['etag'];
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err)
}
Copy to clipboard

Example request

response = iam_identity_service.get_account_settings(account_id=account_id)
settings = response.get_result()
print(json.dumps(settings, indent=2))

Response

Response Body

AccountSettingsResponse

Response body format for Account Settings REST requests.

AccountSettingsResponse

Response body format for Account Settings REST requests.

AccountSettingsResponse

Response body format for Account Settings REST requests.

AccountSettingsResponse

Response body format for Account Settings REST requests.

AccountSettingsResponse

Response body format for Account Settings REST requests.

Status Code

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.
500
Internal Server error. Response if unexpected error situation happened.

Example responses

Status 200

{
  "account_id": "5bbe28be34524avs8a34d37d1f2294a8a",
  "restrict_create_service_id": "NOT_SET",
  "restrict_create_platform_apikey": "NOT_SET",
  "entity_tag": "1-b67c932537dee167ce71be73d59d6a5c",
  "mfa": "NONE",
  "user_mfa": {
    "iam_id": "IBMid-1234567898",
    "mfa": "NONE"
  },
  "session_expiration_in_seconds": "NOT_SET",
  "session_invalidation_in_seconds": "NOT_SET",
  "max_sessions_per_identity": "NOT_SET",
  "system_access_token_expiration_in_seconds": "NOT_SET",
  "system_refresh_token_expiration_in_seconds": "NOT_SET"
}
Copy to clipboard

Success example

{
  "account_id": "5bbe28be34524avs8a34d37d1f2294a8a",
  "restrict_create_service_id": "NOT_SET",
  "restrict_create_platform_apikey": "NOT_SET",
  "entity_tag": "1-b67c932537dee167ce71be73d59d6a5c",
  "mfa": "NONE",
  "user_mfa": {
    "iam_id": "IBMid-1234567898",
    "mfa": "NONE"
  },
  "session_expiration_in_seconds": "NOT_SET",
  "session_invalidation_in_seconds": "NOT_SET",
  "max_sessions_per_identity": "NOT_SET",
  "system_access_token_expiration_in_seconds": "NOT_SET",
  "system_refresh_token_expiration_in_seconds": "NOT_SET"
}
Copy to clipboard

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.

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

(iamIdentity *IamIdentityV1) UpdateAccountSettings(updateAccountSettingsOptions *UpdateAccountSettingsOptions) (result *AccountSettingsResponse, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) UpdateAccountSettingsWithContext(ctx context.Context, updateAccountSettingsOptions *UpdateAccountSettingsOptions) (result *AccountSettingsResponse, response *core.DetailedResponse, err error)

ServiceCall<AccountSettingsResponse> updateAccountSettings(UpdateAccountSettingsOptions updateAccountSettingsOptions)
Copy to clipboard

updateAccountSettings(params)

update_account_settings(
        self,
        if_match: str,
        account_id: str,
        *,
        restrict_create_service_id: Optional[str] = None,
        restrict_create_platform_apikey: Optional[str] = None,
        allowed_ip_addresses: Optional[str] = None,
        mfa: Optional[str] = None,
        user_mfa: Optional[List['AccountSettingsUserMFA']] = None,
        session_expiration_in_seconds: Optional[str] = None,
        session_invalidation_in_seconds: Optional[str] = None,
        max_sessions_per_identity: Optional[str] = None,
        system_access_token_expiration_in_seconds: Optional[str] = None,
        system_refresh_token_expiration_in_seconds: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.account.update

Auditing

Calling this method generates the following auditing event.

iam-identity.accountsettings.update

Request

Instantiate the UpdateAccountSettingsOptions struct and set the fields to provide parameter values for the UpdateAccountSettings method.

Use the UpdateAccountSettingsOptions.Builder to create a UpdateAccountSettingsOptions object that contains the parameter values for the updateAccountSettings method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.
If-Match
Required*
string
Version of the account settings to be updated. Specify the version that you retrieved as entity_tag (ETag header) when reading the account. This value helps identifying parallel usage of this API. Pass * to indicate to update any version available. This might result in stale updates.

Path Parameters

account_id
Required*
string
The id of the account to update the settings for.

Request Body

Required*

AccountSettingsRequest

Request to update an account's settings.

parameter

WithContext method only

UpdateAccountSettingsOptions

The UpdateAccountSettings options.

UpdateAccountSettingsOptions

The updateAccountSettings options.

parameters

ifMatch
Required*
string
Version of the account settings to be updated. Specify the version that you retrieved as entity_tag (ETag header) when reading the account. This value helps identifying parallel usage of this API. Pass * to indicate to update any version available. This might result in stale updates.
accountId
Required*
string
The id of the account to update the settings for.
restrictCreateServiceId
string
Defines whether or not creating a service ID 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.
Allowable values: [RESTRICTED,NOT_RESTRICTED,NOT_SET]
restrictCreatePlatformApikey
string
Defines whether or not creating platform API keys is access controlled. Valid values:
- RESTRICTED - only users assigned the 'User API key creator' role on the IAM Identity Service can create API keys, including the account owner
- NOT_RESTRICTED - all members of an account can create platform API keys
- NOT_SET - to 'unset' a previous set value.
Allowable values: [RESTRICTED,NOT_RESTRICTED,NOT_SET]
allowedIpAddresses
string
Defines the IP addresses and subnets from which IAM tokens can be created for the account.
mfa
string
Defines the MFA trait for the account. Valid values:
- 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 - U2F MFA for all users.
Allowable values: [NONE,NONE_NO_ROPC,TOTP,TOTP4ALL,LEVEL1,LEVEL2,LEVEL3]
userMfa
List of users that are exempted from the MFA requirement of the account.
sessionExpirationInSeconds
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.
Default: 86400
sessionInvalidationInSeconds
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.
Default: 7200
maxSessionsPerIdentity
string
Defines the max allowed sessions per identity required by the account. Value values:
- Any whole number greater than 0
- NOT_SET - To unset account setting and use service default.
systemAccessTokenExpirationInSeconds
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.
Default: 3600
systemRefreshTokenExpirationInSeconds
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.
Default: 259200

parameters

if_match
Required*
str
Version of the account settings to be updated. Specify the version that you retrieved as entity_tag (ETag header) when reading the account. This value helps identifying parallel usage of this API. Pass * to indicate to update any version available. This might result in stale updates.
account_id
Required*
str
The id of the account to update the settings for.
restrict_create_service_id
str
Defines whether or not creating a service ID 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.
Allowable values: [RESTRICTED,NOT_RESTRICTED,NOT_SET]
restrict_create_platform_apikey
str
Defines whether or not creating platform API keys is access controlled. Valid values:
- RESTRICTED - only users assigned the 'User API key creator' role on the IAM Identity Service can create API keys, including the account owner
- NOT_RESTRICTED - all members of an account can create platform API keys
- NOT_SET - to 'unset' a previous set value.
Allowable values: [RESTRICTED,NOT_RESTRICTED,NOT_SET]
allowed_ip_addresses
str
Defines the IP addresses and subnets from which IAM tokens can be created for the account.
mfa
str
Defines the MFA trait for the account. Valid values:
- 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 - U2F MFA for all users.
Allowable values: [NONE,NONE_NO_ROPC,TOTP,TOTP4ALL,LEVEL1,LEVEL2,LEVEL3]
user_mfa
List of users that are exempted from the MFA requirement of the account.
session_expiration_in_seconds
str
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.
Default: 86400
session_invalidation_in_seconds
str
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.
Default: 7200
max_sessions_per_identity
str
Defines the max allowed sessions per identity required by the account. Value values:
- Any whole number greater than 0
- NOT_SET - To unset account setting and use service default.
system_access_token_expiration_in_seconds
str
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.
Default: 3600
system_refresh_token_expiration_in_seconds
str
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.
Default: 259200

Example request

curl -X PUT "https://iam.cloud.ibm.com/v1/accounts/ACCOUNT_ID/settings/identity" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" --header "If-Match: <value of etag header from GET request>" --data '{
    "restrict_create_service_id": "RESTRICTED",
    "restrict_create_platform_apikey": "RESTRICTED",
    "allowed_ip_addresses": "127.0.0.1",
    "mfa": "NONE"
    "session_expiration_in_seconds": "900",
    "session_invalidation_in_seconds": "800",
    "max_sessions_per_identity": "10"
}'
Copy to clipboard

Example request

accountSettingsUserMFA := new(iamidentityv1.AccountSettingsUserMfa)
accountSettingsUserMFA.IamID = core.StringPtr(iamIDMember)
accountSettingsUserMFA.Mfa = core.StringPtr("NONE")

updateAccountSettingsOptions := iamIdentityService.NewUpdateAccountSettingsOptions(
  accountSettingEtag,
  accountID,
)
updateAccountSettingsOptions.SetSessionExpirationInSeconds("86400")
updateAccountSettingsOptions.SetSessionInvalidationInSeconds("7200")
updateAccountSettingsOptions.SetMfa("NONE")
updateAccountSettingsOptions.SetUserMfa([]iamidentityv1.AccountSettingsUserMfa{*accountSettingsUserMFA})
updateAccountSettingsOptions.SetRestrictCreatePlatformApikey("NOT_RESTRICTED")
updateAccountSettingsOptions.SetRestrictCreatePlatformApikey("NOT_RESTRICTED")
updateAccountSettingsOptions.SetSystemAccessTokenExpirationInSeconds("3600")
updateAccountSettingsOptions.SetSystemRefreshTokenExpirationInSeconds("259200")

accountSettingsResponse, response, err := iamIdentityService.UpdateAccountSettings(updateAccountSettingsOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(accountSettingsResponse, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

AccountSettingsUserMFA userMFA = new AccountSettingsUserMFA.Builder()
    .iamId(iamIdMember)
    .mfa("NONE")
    .build();

List<AccountSettingsUserMFA> userMFAExpList = new ArrayList<>();
userMFAExpList.add(userMFA);

UpdateAccountSettingsOptions updateAccountSettingsOptions = new UpdateAccountSettingsOptions.Builder()
    .ifMatch(accountSettingsEtag)
    .accountId(accountId)
    .sessionExpirationInSeconds("86400")
    .sessionInvalidationInSeconds("7200")
    .restrictCreatePlatformApikey("NOT_RESTRICTED")
    .restrictCreateServiceId("NOT_RESTRICTED")
    .mfa("NONE")
    .userMfa(userMFAExpList)
    .systemAccessTokenExpirationInSeconds("3600")
    .systemRefreshTokenExpirationInSeconds("259200")
    .build();

Response<AccountSettingsResponse> response = service.updateAccountSettings(updateAccountSettingsOptions).execute();
AccountSettingsResponse accountSettingsResponse = response.getResult();

System.out.println(accountSettingsResponse);
Copy to clipboard

Example request

const accountSettingsUserMFA = {
  iam_id: iamIdMember,
  mfa: 'NONE',
};

const userMfa = [accountSettingsUserMFA];

const params = {
  ifMatch: accountSettingsEtag,
  accountId: accountId,
  restrictCreateServiceId: "NOT_RESTRICTED",
  restrictCreatePlatformApikey: "NOT_RESTRICTED",
  mfa: "NONE",
  userMfa,
  sessionExpirationInSeconds: "86400",
  sessionInvalidationInSeconds: "7200",
  systemAccessTokenExpirationInSeconds: '3600',
  systemRefreshTokenExpirationInSeconds: '259200',
};

try {
  const res = await iamIdentityService.updateAccountSettings(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err)
}
Copy to clipboard

Example request

account_settings_user_mfa = {}
account_settings_user_mfa['iam_id'] = iam_id_member
account_settings_user_mfa['mfa'] = 'NONE'
account_settings_response = iam_identity_service.update_account_settings(
  account_id=account_id,
  if_match=account_settings_etag,
  restrict_create_service_id="NOT_RESTRICTED",
  restrict_create_platform_apikey="NOT_RESTRICTED",
  mfa="NONE",
  user_mfa=[account_settings_user_mfa],
  session_expiration_in_seconds="86400",
  session_invalidation_in_seconds="7200",
  max_sessions_per_identity='10',
  system_access_token_expiration_in_seconds='3600',
  system_refresh_token_expiration_in_seconds='259200',
).get_result()
print(json.dumps(account_settings_response, indent=2))
Copy to clipboard

Response

Response Body

AccountSettingsResponse

Response body format for Account Settings REST requests.

AccountSettingsResponse

Response body format for Account Settings REST requests.

AccountSettingsResponse

Response body format for Account Settings REST requests.

AccountSettingsResponse

Response body format for Account Settings REST requests.

AccountSettingsResponse

Response body format for Account Settings REST requests.

Status Code

200
Successful account configuration update.
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.

Example responses

Status 200

{
  "account_id": "5bbe28be34524avs8a34d37d1f2294a8a",
  "restrict_create_service_id": "RESTRICTED",
  "restrict_create_platform_apikey": "RESTRICTED",
  "allowed_ip_addresses": "127.0.0.1",
  "entity_tag": "2-b67acg2537dee167ce71be73d59d6a5c",
  "mfa": "NONE",
  "user_mfa": {
    "iam_id": "IBMid-1234567898",
    "mfa": "LEVEL1"
  },
  "session_expiration_in_seconds": "3600",
  "session_invalidation_in_seconds": "1800",
  "max_sessions_per_identity": "10",
  "system_access_token_expiration_in_seconds": "3600",
  "system_refresh_token_expiration_in_seconds": "259200"
}
Copy to clipboard

Success example

{
  "account_id": "5bbe28be34524avs8a34d37d1f2294a8a",
  "restrict_create_service_id": "RESTRICTED",
  "restrict_create_platform_apikey": "RESTRICTED",
  "allowed_ip_addresses": "127.0.0.1",
  "entity_tag": "2-b67acg2537dee167ce71be73d59d6a5c",
  "mfa": "NONE",
  "user_mfa": {
    "iam_id": "IBMid-1234567898",
    "mfa": "LEVEL1"
  },
  "session_expiration_in_seconds": "3600",
  "session_invalidation_in_seconds": "1800",
  "max_sessions_per_identity": "10",
  "system_access_token_expiration_in_seconds": "3600",
  "system_refresh_token_expiration_in_seconds": "259200"
}
Copy to clipboard

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

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

(iamIdentity *IamIdentityV1) GetMfaStatus(getMfaStatusOptions *GetMfaStatusOptions) (result *UserMfaEnrollments, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) GetMfaStatusWithContext(ctx context.Context, getMfaStatusOptions *GetMfaStatusOptions) (result *UserMfaEnrollments, response *core.DetailedResponse, err error)

ServiceCall<UserMfaEnrollments> getMfaStatus(GetMfaStatusOptions getMfaStatusOptions)
Copy to clipboard

getMfaStatus(params)

get_mfa_status(
        self,
        account_id: str,
        iam_id: str,
        **kwargs,
    ) -> DetailedResponse

Authorization

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

iam-identity.mfa-status.get

Request

Instantiate the GetMfaStatusOptions struct and set the fields to provide parameter values for the GetMfaStatus method.

Use the GetMfaStatusOptions.Builder to create a GetMfaStatusOptions object that contains the parameter values for the getMfaStatus method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the 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.

parameter

WithContext method only

GetMfaStatusOptions

The GetMfaStatus options.

GetMfaStatusOptions

The getMfaStatus options.

parameters

accountId
Required*
string
ID of the account.
iamId
Required*
string
iam_id of the user. This user must be the member of the account.

parameters

account_id
Required*
str
ID of the account.
iam_id
Required*
str
iam_id of the user. This user must be the member of the account.

Example request

curl -X GET "https://iam.cloud.ibm.com/v1/mfa/accounts/ACCOUNT_ID/status?iam_id=IAM_ID" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" 
Copy to clipboard

Example request

getMfaStatusOptions := iamIdentityService.NewGetMfaStatusOptions(accountID, iamID)

mfaStatusResponse, response, err := iamIdentityService.GetMfaStatus(getMfaStatusOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(mfaStatusResponse, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

GetMfaStatusOptions getMfaStatusOptions = new GetMfaStatusOptions.Builder()
    .accountId(accountId)
    .iamId(iamId)
    .build();

Response<UserMfaEnrollments> response = service.getMfaStatus(getMfaStatusOptions).execute();
UserMfaEnrollments userMfaEnrollmentsResponse = response.getResult();

System.out.println(userMfaEnrollmentsResponse);

Example request

const params = {
  accountId: accountId,
  iamId: iamId,
};

try {
  const res = await iamIdentityService.getMfaStatus(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

get_mfa_status_response = iam_identity_service.get_mfa_status(
  account_id=account_id, iam_id=iam_id
).get_result()
print(json.dumps(get_mfa_status_response, indent=2))

Response

Response Body

UserMfaEnrollments

Status Code

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
Report not found.
500
Internal Server error. Response if unexpected error situation happened.

Example responses

Status 200

{
  "iam_id": "IBMid-12345678",
  "effective_mfa_type": "id_based_mfa",
  "id_based_mfa": {
    "trait_account_default": "LEVEL3",
    "trait_user_specific\"": "LEVEL2",
    "trait_effective": "LEVEL2",
    "complies": true
  },
  "account_based_mfa": {
    "complies": true,
    "security_questions": {
      "required": true,
      "enrolled": true
    },
    "totp": {
      "required\"": true,
      "enrolled\"": true
    },
    "verisign": {
      "required\"": false,
      "enrolled": false
    }
  }
}
Copy to clipboard

Success example

{
  "iam_id": "IBMid-12345678",
  "effective_mfa_type": "id_based_mfa",
  "id_based_mfa": {
    "trait_account_default": "LEVEL3",
    "trait_user_specific\"": "LEVEL2",
    "trait_effective": "LEVEL2",
    "complies": true
  },
  "account_based_mfa": {
    "complies": true,
    "security_questions": {
      "required": true,
      "enrolled": true
    },
    "totp": {
      "required\"": true,
      "enrolled\"": true
    },
    "verisign": {
      "required\"": false,
      "enrolled": false
    }
  }
}
Copy to clipboard

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.

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

(iamIdentity *IamIdentityV1) CreateMfaReport(createMfaReportOptions *CreateMfaReportOptions) (result *ReportReference, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) CreateMfaReportWithContext(ctx context.Context, createMfaReportOptions *CreateMfaReportOptions) (result *ReportReference, response *core.DetailedResponse, err error)

ServiceCall<ReportReference> createMfaReport(CreateMfaReportOptions createMfaReportOptions)
Copy to clipboard

createMfaReport(params)

create_mfa_report(
        self,
        account_id: str,
        *,
        type: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.report.create

Request

Instantiate the CreateMfaReportOptions struct and set the fields to provide parameter values for the CreateMfaReport method.

Use the CreateMfaReportOptions.Builder to create a CreateMfaReportOptions object that contains the parameter values for the createMfaReport method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the 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.

parameter

WithContext method only

CreateMfaReportOptions

The CreateMfaReport options.

CreateMfaReportOptions

The createMfaReport options.

parameters

accountId
Required*
string
ID of the account.
type
string
Optional report type. The supported value is 'mfa_status'. List MFA enrollment status for all the identities.

parameters

account_id
Required*
str
ID of the account.
type
str
Optional report type. The supported value is 'mfa_status'. List MFA enrollment status for all the identities.

Example request

curl -X POST "https://iam.cloud.ibm.com/v1/mfa/accounts/ACCOUNT_ID/report?type=mfa_status" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" 
Copy to clipboard

Example request

createMfaReportOptions := iamIdentityService.NewCreateMfaReportOptions(accountID)
createMfaReportOptions.SetType("mfa_status")

report, response, err := iamIdentityService.CreateMfaReport(createMfaReportOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(report, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

CreateMfaReportOptions createMfaReportOptions = new CreateMfaReportOptions.Builder()
    .accountId(accountId)
    .type("mfa_status")
    .build();

Response<ReportReference> response = service.createMfaReport(createMfaReportOptions).execute();
ReportReference reportReference = response.getResult();

reportReferenceValue = reportReference.getReference();

System.out.println(reportReferenceValue);

Example request

const params = {
  accountId: accountId,
  type: 'mfa_status',
};

try {
  const res = await iamIdentityService.createMfaReport(params);
  reportReferenceMfa = res.result.reference;
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

create_report_response = iam_identity_service.create_mfa_report(
  account_id=account_id, type="mfa_status"
).get_result()
print(json.dumps(create_report_response, indent=2))
Copy to clipboard

Response

Response Body

ReportReference

Status Code

202
Create report accepted.
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.

Example responses

Status 202

{
  "reference": "abc11111-b222-c333-d444-abc123def456"
}

Success example

{
  "reference": "abc11111-b222-c333-d444-abc123def456"
}

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.

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

(iamIdentity *IamIdentityV1) GetMfaReport(getMfaReportOptions *GetMfaReportOptions) (result *ReportMfaEnrollmentStatus, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) GetMfaReportWithContext(ctx context.Context, getMfaReportOptions *GetMfaReportOptions) (result *ReportMfaEnrollmentStatus, response *core.DetailedResponse, err error)

ServiceCall<ReportMfaEnrollmentStatus> getMfaReport(GetMfaReportOptions getMfaReportOptions)
Copy to clipboard

getMfaReport(params)

get_mfa_report(
        self,
        account_id: str,
        reference: str,
        **kwargs,
    ) -> DetailedResponse

Authorization

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

iam-identity.report.get

Request

Instantiate the GetMfaReportOptions struct and set the fields to provide parameter values for the GetMfaReport method.

Use the GetMfaReportOptions.Builder to create a GetMfaReportOptions object that contains the parameter values for the getMfaReport method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the 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.

parameter

WithContext method only

GetMfaReportOptions

The GetMfaReport options.

GetMfaReportOptions

The getMfaReport options.

parameters

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

parameters

account_id
Required*
str
ID of the account.
reference
Required*
str
Reference for the report to be generated, You can use 'latest' to get the latest report for the given account.

Example request

curl -X GET "https://iam.cloud.ibm.com/v1/mfa/accounts/ACCOUNT_ID/report/REFERENCE" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" 
Copy to clipboard

Example request

getMfaReportOptions := iamIdentityService.NewGetMfaReportOptions(accountID, "latest")

report, response, err := iamIdentityService.GetMfaReport(getMfaReportOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(report, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

GetMfaReportOptions getMfaReportOptions = new GetMfaReportOptions.Builder()
    .accountId(accountId)
    .reference(reportReferenceValue)
    .build();

Response<ReportMfaEnrollmentStatus> response = service.getMfaReport(getMfaReportOptions).execute();
ReportMfaEnrollmentStatus fetchedReport = response.getResult();

System.out.println(fetchedReport);

Example request

const params = {
  accountId: accountId,
  reference: 'latest',
};

try {
  const res = await iamIdentityService.getMfaReport(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

get_report_response = iam_identity_service.get_mfa_report(
  account_id=account_id, reference=report_reference_mfa
).get_result()
print(json.dumps(get_report_response, indent=2))

Response

Response Body

ReportMfaEnrollmentStatus

Status Code

200
Successful - report retrieved.
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.

Example responses

Status 200

{
  "created_by": "iam-id",
  "reference": "abc11111-b222-c333-d444-abc123def456",
  "report_time": "2022-01-24T19:07:37:999+0000",
  "account_id": "BSS_account_id",
  "ims_account_id": "IMS_account_id",
  "users": {
    "iam_id": "IBMid-12345678",
    "name": "Name123",
    "username": "user@ibm.com",
    "email": "user@ibm.com"
  },
  "enrollments": {
    "effective_mfa_type": "id_based_mfa",
    "id_based_mfa": {
      "trait_account_default": "LEVEL3",
      "trait_user_specific\"": "LEVEL2",
      "trait_effective": "LEVEL2",
      "complies": true
    },
    "account_based_mfa": {
      "complies": true,
      "security_questions": {
        "required": true,
        "enrolled": true
      },
      "totp": {
        "required\"": true,
        "enrolled\"": true
      },
      "verisign": {
        "required\"": false,
        "enrolled": false
      }
    }
  }
}
Copy to clipboard

Success example

{
  "created_by": "iam-id",
  "reference": "abc11111-b222-c333-d444-abc123def456",
  "report_time": "2022-01-24T19:07:37:999+0000",
  "account_id": "BSS_account_id",
  "ims_account_id": "IMS_account_id",
  "users": {
    "iam_id": "IBMid-12345678",
    "name": "Name123",
    "username": "user@ibm.com",
    "email": "user@ibm.com"
  },
  "enrollments": {
    "effective_mfa_type": "id_based_mfa",
    "id_based_mfa": {
      "trait_account_default": "LEVEL3",
      "trait_user_specific\"": "LEVEL2",
      "trait_effective": "LEVEL2",
      "complies": true
    },
    "account_based_mfa": {
      "complies": true,
      "security_questions": {
        "required": true,
        "enrolled": true
      },
      "totp": {
        "required\"": true,
        "enrolled\"": true
      },
      "verisign": {
        "required\"": false,
        "enrolled": false
      }
    }
  }
}
Copy to clipboard

Returns effective account settings for given account ID

Returns effective account settings for given account ID.

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

(iamIdentity *IamIdentityV1) GetEffectiveAccountSettings(getEffectiveAccountSettingsOptions *GetEffectiveAccountSettingsOptions) (result *EffectiveAccountSettingsResponse, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) GetEffectiveAccountSettingsWithContext(ctx context.Context, getEffectiveAccountSettingsOptions *GetEffectiveAccountSettingsOptions) (result *EffectiveAccountSettingsResponse, response *core.DetailedResponse, err error)

ServiceCall<EffectiveAccountSettingsResponse> getEffectiveAccountSettings(GetEffectiveAccountSettingsOptions getEffectiveAccountSettingsOptions)
Copy to clipboard

getEffectiveAccountSettings(params)

get_effective_account_settings(
        self,
        account_id: str,
        *,
        include_history: Optional[bool] = None,
        resolve_user_mfa: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.account.getEffectiveAccountSettings

Request

Instantiate the GetEffectiveAccountSettingsOptions struct and set the fields to provide parameter values for the GetEffectiveAccountSettings method.

Use the GetEffectiveAccountSettingsOptions.Builder to create a GetEffectiveAccountSettingsOptions object that contains the parameter values for the getEffectiveAccountSettings method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the 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.

Default: false
resolve_user_mfa
boolean
Enrich MFA exemptions with user information.

Default: false

parameter

WithContext method only

GetEffectiveAccountSettingsOptions

The GetEffectiveAccountSettings options.

GetEffectiveAccountSettingsOptions

The getEffectiveAccountSettings options.

parameters

accountId
Required*
string
Unique ID of the account.
includeHistory
boolean
Defines if the entity history is included in the response.

Default: false
resolveUserMfa
boolean
Enrich MFA exemptions with user information.

Default: false

parameters

account_id
Required*
str
Unique ID of the account.
include_history
bool
Defines if the entity history is included in the response.

Default: false
resolve_user_mfa
bool
Enrich MFA exemptions with user information.

Default: false

Example request

curl -X GET "https://iam.test.cloud.ibm.com/v1/accounts/ACCOUNT_ID/effective_settings/identity" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" 
Copy to clipboard

Example request

getEffectiveAccountSettingsOptions := iamIdentityService.NewGetEffectiveAccountSettingsOptions(accountID)

effectiveAccountSettingsResponse, response, err := iamIdentityService.GetEffectiveAccountSettings(getEffectiveAccountSettingsOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(effectiveAccountSettingsResponse, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

GetEffectiveAccountSettingsOptions getEffectiveAccountSettingsOptions = new GetEffectiveAccountSettingsOptions.Builder()
    .accountId(accountId)
    .build();

Response<EffectiveAccountSettingsResponse> response = service.getEffectiveAccountSettings(getEffectiveAccountSettingsOptions).execute();
EffectiveAccountSettingsResponse effectiveAccountSettingsResponse = response.getResult();


System.out.println(effectiveAccountSettingsResponse);

Example request

const params = {
  accountId: accountId,
};

try {
  const res = await iamIdentityService.getEffectiveAccountSettings(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err)
}
Copy to clipboard

Example request

response = iam_identity_service.get_effective_account_settings(account_id=account_id)
settings = response.get_result()
print(json.dumps(settings, indent=2))

Response

Response Body

EffectiveAccountSettingsResponse

Response body format for Account Settings REST requests.

EffectiveAccountSettingsResponse

Response body format for Account Settings REST requests.

EffectiveAccountSettingsResponse

Response body format for Account Settings REST requests.

EffectiveAccountSettingsResponse

Response body format for Account Settings REST requests.

EffectiveAccountSettingsResponse

Response body format for Account Settings REST requests.

Status Code

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.
500
Internal Server error. Response if unexpected error situation happened.

Example responses

Status 200

{
  "account_id": "c847c915b2fbde106934e45d43993103",
  "effective": {
    "restrict_create_service_id": "NOT_SET",
    "restrict_create_platform_apikey": "NOT_SET",
    "allowed_ip_addresses": null,
    "mfa": "NONE",
    "user_mfa": [
      {
        "iam_id": "iam-internal",
        "mfa": "NONE",
        "name": "name",
        "userName": "username",
        "email": "email",
        "description\"": "description"
      }
    ],
    "session_expiration_in_seconds": 50,
    "session_invalidation_in_seconds": "NOT_SET",
    "max_sessions_per_identity": "NOT_SET",
    "system_access_token_expiration_in_seconds": "NOT_SET",
    "system_refresh_token_expiration_in_seconds": "NOT_SET"
  },
  "account": {
    "account_id": "c847c915b2fbde106934e45d43993103",
    "restrict_create_service_id": "NOT_SET",
    "restrict_create_platform_apikey": "NOT_SET",
    "allowed_ip_addresses": null,
    "entity_tag": "1701-5237bb550c744bad0d8d0303b2f51bae",
    "mfa": "NONE",
    "user_mfa": [
      {
        "iam_id": "iam-internal",
        "mfa": "NONE",
        "name": "name",
        "userName": "username",
        "email": "email",
        "description": "description"
      }
    ],
    "history": [
      {
        "timestamp": "2024-02-22T13:54+0000",
        "iam_id": "iam-internal",
        "action": "iam-identity.optout.applied",
        "params": [
          "account_mfa_default_noropc NONE mfa_not_updated timestamp=1708610075198"
        ],
        "message": "iam-identity.optout.applied"
      }
    ],
    "session_expiration_in_seconds": 50,
    "session_invalidation_in_seconds": "NOT_SET",
    "max_sessions_per_identity": "NOT_SET",
    "system_access_token_expiration_in_seconds": "NOT_SET",
    "system_refresh_token_expiration_in_seconds": "NOT_SET"
  },
  "assigned_templates": [
    {
      "template_id": "template_id",
      "template_name": "template_name",
      "template_version": 123456,
      "restrict_create_service_id": "NOT_SET",
      "restrict_create_platform_apikey": "NOT_SET",
      "allowed_ip_addresses": null,
      "mfa": "NONE",
      "user_mfa": [
        {
          "iam_id": "iam-internal",
          "mfa": "NONE",
          "name": "name",
          "userName": "username",
          "email": "email",
          "description": "description"
        }
      ],
      "session_expiration_in_seconds": 50,
      "session_invalidation_in_seconds": "NOT_SET",
      "max_sessions_per_identity": "NOT_SET",
      "system_access_token_expiration_in_seconds": "NOT_SET",
      "system_refresh_token_expiration_in_seconds": "NOT_SET"
    }
  ]
}
Copy to clipboard

Success example

{
  "account_id": "c847c915b2fbde106934e45d43993103",
  "effective": {
    "restrict_create_service_id": "NOT_SET",
    "restrict_create_platform_apikey": "NOT_SET",
    "allowed_ip_addresses": null,
    "mfa": "NONE",
    "user_mfa": [
      {
        "iam_id": "iam-internal",
        "mfa": "NONE",
        "name": "name",
        "userName": "username",
        "email": "email",
        "description\"": "description"
      }
    ],
    "session_expiration_in_seconds": 50,
    "session_invalidation_in_seconds": "NOT_SET",
    "max_sessions_per_identity": "NOT_SET",
    "system_access_token_expiration_in_seconds": "NOT_SET",
    "system_refresh_token_expiration_in_seconds": "NOT_SET"
  },
  "account": {
    "account_id": "c847c915b2fbde106934e45d43993103",
    "restrict_create_service_id": "NOT_SET",
    "restrict_create_platform_apikey": "NOT_SET",
    "allowed_ip_addresses": null,
    "entity_tag": "1701-5237bb550c744bad0d8d0303b2f51bae",
    "mfa": "NONE",
    "user_mfa": [
      {
        "iam_id": "iam-internal",
        "mfa": "NONE",
        "name": "name",
        "userName": "username",
        "email": "email",
        "description": "description"
      }
    ],
    "history": [
      {
        "timestamp": "2024-02-22T13:54+0000",
        "iam_id": "iam-internal",
        "action": "iam-identity.optout.applied",
        "params": [
          "account_mfa_default_noropc NONE mfa_not_updated timestamp=1708610075198"
        ],
        "message": "iam-identity.optout.applied"
      }
    ],
    "session_expiration_in_seconds": 50,
    "session_invalidation_in_seconds": "NOT_SET",
    "max_sessions_per_identity": "NOT_SET",
    "system_access_token_expiration_in_seconds": "NOT_SET",
    "system_refresh_token_expiration_in_seconds": "NOT_SET"
  },
  "assigned_templates": [
    {
      "template_id": "template_id",
      "template_name": "template_name",
      "template_version": 123456,
      "restrict_create_service_id": "NOT_SET",
      "restrict_create_platform_apikey": "NOT_SET",
      "allowed_ip_addresses": null,
      "mfa": "NONE",
      "user_mfa": [
        {
          "iam_id": "iam-internal",
          "mfa": "NONE",
          "name": "name",
          "userName": "username",
          "email": "email",
          "description": "description"
        }
      ],
      "session_expiration_in_seconds": 50,
      "session_invalidation_in_seconds": "NOT_SET",
      "max_sessions_per_identity": "NOT_SET",
      "system_access_token_expiration_in_seconds": "NOT_SET",
      "system_refresh_token_expiration_in_seconds": "NOT_SET"
    }
  ]
}
Copy to clipboard

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

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

(iamIdentity *IamIdentityV1) CreateReport(createReportOptions *CreateReportOptions) (result *ReportReference, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) CreateReportWithContext(ctx context.Context, createReportOptions *CreateReportOptions) (result *ReportReference, response *core.DetailedResponse, err error)

ServiceCall<ReportReference> createReport(CreateReportOptions createReportOptions)
Copy to clipboard

createReport(params)

create_report(
        self,
        account_id: str,
        *,
        type: Optional[str] = None,
        duration: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.report.create

Request

Instantiate the CreateReportOptions struct and set the fields to provide parameter values for the CreateReport method.

Use the CreateReportOptions.Builder to create a CreateReportOptions object that contains the parameter values for the createReport method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the 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.

Default: inactive
duration
string
Optional duration of the report. The supported unit of duration is hours.

Default: 720

parameter

WithContext method only

CreateReportOptions

The CreateReport options.

CreateReportOptions

The createReport options.

parameters

accountId
Required*
string
ID of the account.
type
string
Optional report type. The supported value is 'inactive'. List all identities that have not authenticated within the time indicated by duration.

Default: inactive
duration
string
Optional duration of the report. The supported unit of duration is hours.

Default: 720

parameters

account_id
Required*
str
ID of the account.
type
str
Optional report type. The supported value is 'inactive'. List all identities that have not authenticated within the time indicated by duration.

Default: inactive
duration
str
Optional duration of the report. The supported unit of duration is hours.

Default: 720

Example request

curl -X POST "https://iam.cloud.ibm.com/v1/activity/accounts/ACCOUNT_ID/report" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" 
Copy to clipboard

Example request

createReportOptions := iamIdentityService.NewCreateReportOptions(accountID)
createReportOptions.SetType("inactive")
createReportOptions.SetDuration("120")

report, response, err := iamIdentityService.CreateReport(createReportOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(report, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

CreateReportOptions createReportOptions = new CreateReportOptions.Builder()
    .accountId(accountId)
    .build();

Response<ReportReference> response = service.createReport(createReportOptions).execute();
ReportReference reportReference = response.getResult();

reportReferenceValue = reportReference.getReference();

System.out.println(reportReferenceValue);

Example request

const params = {
  accountId: accountId,
  type: 'inactive',
  duration: '120',
};

try {
  const res = await iamIdentityService.createReport(params);
  reportReference = res.reference;
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

create_report_response = iam_identity_service.create_report(
  account_id=account_id,
  type="inactive",
  duration="120",
).get_result()
print(json.dumps(create_report_response, indent=2))
Copy to clipboard

Response

Response Body

ReportReference

Status Code

202
Create report accepted.
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.

Example responses

Status 202

{
  "reference": "abc11111-b222-c333-d444-abc123def456"
}

Success example

{
  "reference": "abc11111-b222-c333-d444-abc123def456"
}

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.

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

(iamIdentity *IamIdentityV1) GetReport(getReportOptions *GetReportOptions) (result *Report, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) GetReportWithContext(ctx context.Context, getReportOptions *GetReportOptions) (result *Report, response *core.DetailedResponse, err error)

ServiceCall<Report> getReport(GetReportOptions getReportOptions)
Copy to clipboard

getReport(params)

get_report(
        self,
        account_id: str,
        reference: str,
        **kwargs,
    ) -> DetailedResponse

Authorization

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

iam-identity.report.get

Request

Instantiate the GetReportOptions struct and set the fields to provide parameter values for the GetReport method.

Use the GetReportOptions.Builder to create a GetReportOptions object that contains the parameter values for the getReport method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the 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.

parameter

WithContext method only

GetReportOptions

The GetReport options.

GetReportOptions

The getReport options.

parameters

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

parameters

account_id
Required*
str
ID of the account.
reference
Required*
str
Reference for the report to be generated, You can use 'latest' to get the latest report for the given account.

Example request

curl -X GET "https://iam.cloud.ibm.com/v1/activity/accounts/ACCOUNT_ID/report/REFERENCE" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" 
Copy to clipboard

Example request

getReportOptions := iamIdentityService.NewGetReportOptions(accountID, "latest")

report, response, err := iamIdentityService.GetReport(getReportOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(report, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

GetReportOptions getReportOptions = new GetReportOptions.Builder()
    .accountId(accountId)
    .reference(reportReferenceValue)
    .build();

Response<Report> response = service.getReport(getReportOptions).execute();
Report fetchedReport = response.getResult();

System.out.println(fetchedReport);

Example request

const params = {
  accountId: accountId,
  reference: 'latest',
};

try {
  const res = await iamIdentityService.getReport(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

get_report_response = iam_identity_service.get_report(
  account_id=account_id, reference="latest"
).get_result()
print(json.dumps(get_report_response, indent=2))
Copy to clipboard

Response

Response Body

Report

Status Code

200
Successful - report retrieved.
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.

Example responses

Status 200

{
  "created_by": "iam-id",
  "reference": "abc11111-b222-c333-d444-abc123def456",
  "report_duration": 720,
  "report_start_time": "2022-01-24T19:07:37:999+0000",
  "report_end_time": "2022-30-24T19:07:37:999+0000",
  "users": {
    "iam_id": "IBMid-12345678",
    "name": "Name123",
    "username": "user@ibm.com",
    "email": "user@ibm.com",
    "last_authn": "2022-03-18T19:07:37:999+0000"
  },
  "serviceids": {
    "id": "serviceid-123",
    "name": "nice serviceid",
    "last_authn": "2022-03-18T19:07:37:999+0000"
  },
  "profiles": {
    "id": "profileid-123",
    "name": "nice profile",
    "last_authn": "2022-03-18T19:07:37:999+0000"
  },
  "apikeys": [
    {
      "id": "apikey-123",
      "name": "sample serviceid apikey",
      "type": "serviceid",
      "serviceid": {
        "id": "serviceid-123",
        "name": "sample serviceid"
      },
      "last_authn": "2022-03-18T19:07:37:999+0000"
    },
    {
      "id": "apikey-456",
      "name": "sample user apikey",
      "type": "user",
      "user": {
        "iam_id": "IBMid-4567",
        "name": "Name456",
        "username": "user@ibm.com",
        "email": "user@ibm.com"
      },
      "last_authn": "2022-03-10T19:07:37:999+0000"
    }
  ]
}
Copy to clipboard

Success example

{
  "created_by": "iam-id",
  "reference": "abc11111-b222-c333-d444-abc123def456",
  "report_duration": 720,
  "report_start_time": "2022-01-24T19:07:37:999+0000",
  "report_end_time": "2022-30-24T19:07:37:999+0000",
  "users": {
    "iam_id": "IBMid-12345678",
    "name": "Name123",
    "username": "user@ibm.com",
    "email": "user@ibm.com",
    "last_authn": "2022-03-18T19:07:37:999+0000"
  },
  "serviceids": {
    "id": "serviceid-123",
    "name": "nice serviceid",
    "last_authn": "2022-03-18T19:07:37:999+0000"
  },
  "profiles": {
    "id": "profileid-123",
    "name": "nice profile",
    "last_authn": "2022-03-18T19:07:37:999+0000"
  },
  "apikeys": [
    {
      "id": "apikey-123",
      "name": "sample serviceid apikey",
      "type": "serviceid",
      "serviceid": {
        "id": "serviceid-123",
        "name": "sample serviceid"
      },
      "last_authn": "2022-03-18T19:07:37:999+0000"
    },
    {
      "id": "apikey-456",
      "name": "sample user apikey",
      "type": "user",
      "user": {
        "iam_id": "IBMid-4567",
        "name": "Name456",
        "username": "user@ibm.com",
        "email": "user@ibm.com"
      },
      "last_authn": "2022-03-10T19:07:37:999+0000"
    }
  ]
}
Copy to clipboard

List the trusted profile templates in an enterprise account.

GET /v1/profile_templates

(iamIdentity *IamIdentityV1) ListProfileTemplates(listProfileTemplatesOptions *ListProfileTemplatesOptions) (result *TrustedProfileTemplateList, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) ListProfileTemplatesWithContext(ctx context.Context, listProfileTemplatesOptions *ListProfileTemplatesOptions) (result *TrustedProfileTemplateList, response *core.DetailedResponse, err error)

ServiceCall<TrustedProfileTemplateList> listProfileTemplates(ListProfileTemplatesOptions listProfileTemplatesOptions)
Copy to clipboard

listProfileTemplates(params)

list_profile_templates(
        self,
        *,
        account_id: Optional[str] = None,
        limit: Optional[str] = None,
        pagetoken: Optional[str] = None,
        sort: Optional[str] = None,
        order: Optional[str] = None,
        include_history: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.profile-template.read

Request

Instantiate the ListProfileTemplatesOptions struct and set the fields to provide parameter values for the ListProfileTemplates method.

Use the ListProfileTemplatesOptions.Builder to create a ListProfileTemplatesOptions object that contains the parameter values for the listProfileTemplates method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

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.

Possible values: 1 ≤ value ≤ 100
Default: 20
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.

Allowable values: [created_at,last_modified_at,name]
Default: created_at
order
string
Optional sort order.

Allowable values: [asc,desc]
Default: asc
include_history
string
Defines if the entity history is included in the response.

Default: false

parameter

WithContext method only

ListProfileTemplatesOptions

The ListProfileTemplates options.

ListProfileTemplatesOptions

The listProfileTemplates options.

parameters

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

Possible values: 1 ≤ value ≤ 100
Default: 20
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.

Allowable values: [created_at,last_modified_at,name]
Default: created_at
order
string
Optional sort order.

Allowable values: [asc,desc]
Default: asc
includeHistory
string
Defines if the entity history is included in the response.

Default: false

parameters

account_id
str
Account ID of the trusted profile templates to query. This parameter is required unless using a pagetoken.
limit
str
Optional size of a single page.

Possible values: 1 ≤ value ≤ 100
Default: 20
pagetoken
str
Optional Prev or Next page token returned from a previous query execution. Default is start with first page.
sort
str
Optional sort property. If specified, the returned templates are sorted according to this property.

Allowable values: [created_at,last_modified_at,name]
Default: created_at
order
str
Optional sort order.

Allowable values: [asc,desc]
Default: asc
include_history
str
Defines if the entity history is included in the response.

Default: false

Example request

curl -X GET "https://iam.cloud.ibm.com/v1/profile_templates?account_id=5bbe28be34524sdbdaa34d37d1f2294a" --header "Content-Type: application/json" --header "Authorization: Bearer $TOKEN" 
Copy to clipboard

Example request

listOptions := &iamidentityv1.ListProfileTemplatesOptions{
  AccountID: &enterpriseAccountID,
}
listResponse, response, err := iamIdentityService.ListProfileTemplates(listOptions)

b, _ := json.MarshalIndent(listResponse, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

ListProfileTemplatesOptions listOptions = new ListProfileTemplatesOptions.Builder()
    .accountId(enterpriseAccountId)
    .build();

Response<TrustedProfileTemplateList> response = service.listProfileTemplates(listOptions).execute();
TrustedProfileTemplateList listResult = response.getResult();
System.out.println(listResult);

Example request

const params = {
  accountId: enterpriseAccountId,
}
try {
  const res = await iamIdentityService.listProfileTemplates(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

list_response = iam_identity_service.list_profile_templates(account_id=enterprise_account_id)
profile_template_list = list_response.get_result()
print('\nlist_profile_templates response: ', json.dumps(profile_template_list, indent=2))
Copy to clipboard

Response

Response Body

TrustedProfileTemplateList

Status Code

200
Successful Template retrieval
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

Example responses

Status 200

{
  "offset": 0,
  "limit": 20,
  "first": "https://iam.cloud.ibm.com/v1/profile_templates?account_id=5bbe28be34524sdbdaa34d37d1f2294a",
  "profile_templates": [
    {
      "id": "ProfileTemplate-2c434aba-38a4-402c-a8a1-c444570b7408",
      "version": 1,
      "account_id": "5bbe28be34524sdbdaa34d37d1f2294a",
      "name": "My new profile template",
      "committed": true,
      "profile": {
        "name": "Profile from template",
        "description": "this is my spanking profile created from a template v1",
        "rules": [
          {
            "type": "Profile-SAML",
            "realm_name": "idp_realm_name",
            "expiration": 43200,
            "conditions": [
              {
                "claim": "name",
                "operator": "EQUALS",
                "value": "\"MyName\""
              }
            ]
          }
        ]
      },
      "policy_template_references": [
        {
          "id": "Policy_Template-ABCD",
          "version": "1"
        },
        {
          "id": "Policy_Template-ABCDe",
          "version": "1"
        }
      ],
      "action_controls": {
        "identities": {
          "add": false,
          "remove": true
        },
        "rules": {
          "add": true,
          "remove": true
        },
        "policies": {
          "add": false,
          "remove": true
        }
      },
      "created_at": "2023-01-12T13:09:59:761+0000",
      "created_by_id": "IBMid-12345678901",
      "last_modified_at": "2023-02-24T13:48:44:198+0000",
      "last_modified_by_id": "IBMid-12345678901",
      "entity_tag": "6-aa54ac91e59055f80b58da2c5a4c426f",
      "crn": "crn:v1:bluemix:public:iam-identity::a/5bbe28be34524sdbdaa34d37d1f2294a::template:ProfileTemplate-2c434aba-38a4-402c-a8a1-c444570b7408"
    }
  ]
}
Copy to clipboard

Success example

{
  "offset": 0,
  "limit": 20,
  "first": "https://iam.cloud.ibm.com/v1/profile_templates?account_id=5bbe28be34524sdbdaa34d37d1f2294a",
  "profile_templates": [
    {
      "id": "ProfileTemplate-2c434aba-38a4-402c-a8a1-c444570b7408",
      "version": 1,
      "account_id": "5bbe28be34524sdbdaa34d37d1f2294a",
      "name": "My new profile template",
      "committed": true,
      "profile": {
        "name": "Profile from template",
        "description": "this is my spanking profile created from a template v1",
        "rules": [
          {
            "type": "Profile-SAML",
            "realm_name": "idp_realm_name",
            "expiration": 43200,
            "conditions": [
              {
                "claim": "name",
                "operator": "EQUALS",
                "value": "\"MyName\""
              }
            ]
          }
        ]
      },
      "policy_template_references": [
        {
          "id": "Policy_Template-ABCD",
          "version": "1"
        },
        {
          "id": "Policy_Template-ABCDe",
          "version": "1"
        }
      ],
      "action_controls": {
        "identities": {
          "add": false,
          "remove": true
        },
        "rules": {
          "add": true,
          "remove": true
        },
        "policies": {
          "add": false,
          "remove": true
        }
      },
      "created_at": "2023-01-12T13:09:59:761+0000",
      "created_by_id": "IBMid-12345678901",
      "last_modified_at": "2023-02-24T13:48:44:198+0000",
      "last_modified_by_id": "IBMid-12345678901",
      "entity_tag": "6-aa54ac91e59055f80b58da2c5a4c426f",
      "crn": "crn:v1:bluemix:public:iam-identity::a/5bbe28be34524sdbdaa34d37d1f2294a::template:ProfileTemplate-2c434aba-38a4-402c-a8a1-c444570b7408"
    }
  ]
}
Copy to clipboard

Create a new trusted profile template in an enterprise account.

POST /v1/profile_templates

(iamIdentity *IamIdentityV1) CreateProfileTemplate(createProfileTemplateOptions *CreateProfileTemplateOptions) (result *TrustedProfileTemplateResponse, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) CreateProfileTemplateWithContext(ctx context.Context, createProfileTemplateOptions *CreateProfileTemplateOptions) (result *TrustedProfileTemplateResponse, response *core.DetailedResponse, err error)

ServiceCall<TrustedProfileTemplateResponse> createProfileTemplate(CreateProfileTemplateOptions createProfileTemplateOptions)
Copy to clipboard

createProfileTemplate(params)

create_profile_template(
        self,
        *,
        account_id: Optional[str] = None,
        name: Optional[str] = None,
        description: Optional[str] = None,
        profile: Optional['TemplateProfileComponentRequest'] = None,
        policy_template_references: Optional[List['PolicyTemplateReference']] = None,
        action_controls: Optional['ActionControls'] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.profile-template.create

Request

Instantiate the CreateProfileTemplateOptions struct and set the fields to provide parameter values for the CreateProfileTemplate method.

Use the CreateProfileTemplateOptions.Builder to create a CreateProfileTemplateOptions object that contains the parameter values for the createProfileTemplate method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Request Body

Required*

TrustedProfileTemplateRequest

Request to create a trusted profile template.

parameter

WithContext method only

CreateProfileTemplateOptions

The CreateProfileTemplate options.

CreateProfileTemplateOptions

The createProfileTemplate options.

parameters

accountId
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
Input body parameters for the TemplateProfileComponent.
policyTemplateReferences
Existing policy templates that you can reference to assign access in the trusted profile component.
actionControls

parameters

account_id
str
ID of the account where the template resides.
name
str
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
str
The description of the trusted profile template. Describe the template for enterprise account users.
profile
Input body parameters for the TemplateProfileComponent.
policy_template_references
Existing policy templates that you can reference to assign access in the trusted profile component.
action_controls

Example request

curl -X POST "https://iam.cloud.ibm.com/v1/profile_templates" --header "Content-Type: application/json" --header "Authorization: Bearer $TOKEN" --data '{
    "account_id": "5bbe28be34524sdbdaa34d37d1f2294a",
    "name": "db admin template",
    "profile": {
        "name": "Profile for DB Admins",
        "description": "allows users to admin db instances",
        "identities": [
            {
                "type": "user",
                "identifier": "IBMid-123456789",
                "accounts": [
                    "5bbe28be34524sdbdaa34d37d1f2294a"
                ]
            }
        ],
        "rules": [
            {
                "type": "Profile",
                "realm_name": "${IDP_REALM_NAME}",
                "expiration": 43200,
                "conditions": [
                    {
                        "claim": "name",
                        "operator": "EQUALS",
                        "value": "\"My Name\""
                    }
                ]
            }
        ]
    },
    "policy_template_references": [
        {
            "id": "Policy Template-12345",
            "version": 1
        }
    ]
}'
Copy to clipboard

Example request

profileClaimRuleConditions := new(iamidentityv1.ProfileClaimRuleConditions)
profileClaimRuleConditions.Claim = core.StringPtr("blueGroups")
profileClaimRuleConditions.Operator = core.StringPtr("EQUALS")
profileClaimRuleConditions.Value = core.StringPtr("\"cloud-docs-dev\"")

profileTemplateClaimRule := new(iamidentityv1.TrustedProfileTemplateClaimRule)
profileTemplateClaimRule.Name = core.StringPtr("My Rule")
profileTemplateClaimRule.RealmName = &realmName
profileTemplateClaimRule.Type = &claimRuleType
profileTemplateClaimRule.Expiration = core.Int64Ptr(int64(43200))
profileTemplateClaimRule.Conditions = []iamidentityv1.ProfileClaimRuleConditions{*profileClaimRuleConditions}

profile := new(iamidentityv1.TemplateProfileComponentRequest)
profile.Name = &profileTemplateProfileName
profile.Description = core.StringPtr("Example Profile created from Profile Template")
profile.Rules = []iamidentityv1.TrustedProfileTemplateClaimRule{*profileTemplateClaimRule}

createOptions := &iamidentityv1.CreateProfileTemplateOptions{
  Name:        &profileTemplateName,
  Description: core.StringPtr("Example Profile Template"),
  AccountID:   &enterpriseAccountID,
  Profile:     profile,
}

createResponse, response, err := iamIdentityService.CreateProfileTemplate(createOptions)

b, _ := json.MarshalIndent(createResponse, "", "  ")
fmt.Println(string(b))

// Grab the ID and Etag value from the response for use in the update operation
profileTemplateId = *createResponse.ID
profileTemplateVersion = *createResponse.Version
profileTemplateEtag = response.GetHeaders().Get("Etag")
Copy to clipboard

Example request

ProfileClaimRuleConditions condition = new ProfileClaimRuleConditions.Builder()
    .claim("blueGroups")
    .operator("EQUALS")
    .value("\"cloud-docs-dev\"")
    .build();
List<ProfileClaimRuleConditions> conditions = new ArrayList<>();
conditions.add(condition);

TrustedProfileTemplateClaimRule claimRule = new TrustedProfileTemplateClaimRule.Builder()
    .name("My Rule")
    .realmName(realmName)
    .type(claimRuleType)
    .expiration(43200)
    .conditions(conditions)
    .build();

TemplateProfileComponentRequest profile = new TemplateProfileComponentRequest.Builder()
    .addRules(claimRule)
    .name(profileTemplateProfileName)
    .description("Trusted profile created from a template")
    .build();

CreateProfileTemplateOptions createProfileTemplateOptions = new CreateProfileTemplateOptions.Builder()
    .name(profileTemplateName)
    .description("IAM enterprise trusted profile template example")
    .accountId(enterpriseAccountId)
    .profile(profile)
    .build();

Response<TrustedProfileTemplateResponse> response = service.createProfileTemplate(createProfileTemplateOptions).execute();
TrustedProfileTemplateResponse trustedProfileTemplateResult = response.getResult();

// Save the id for use by other test methods.
profileTemplateId = trustedProfileTemplateResult.getId();
profileTemplateVersion = trustedProfileTemplateResult.getVersion().longValue();

System.out.println(trustedProfileTemplateResult);
Copy to clipboard

Example request

const condition = {
  claim: "blueGroups",
  operator: "EQUALS",
  value: "\"cloud-docs-dev\"",
}
const claimRule = {
   name: "My Rule",
   realm_name: realmName,
   type: 'Profile-SAML',
   expiration: 43200,
   conditions: [condition],
}
const profile = {
  rules: [claimRule],
  name: "Profile-From-Example-Template",
  description: "Trusted profile created from a template",
}
const templateParams = {
  name: "Example-Profile-Template",
  description: "IAM enterprise trusted profile template example",
  accountId: enterpriseAccountId,
  profile: profile,
}

try {
  const res = await iamIdentityService.createProfileTemplate(templateParams);
  profileTemplateEtag = res.headers.etag;
  const { result } = res;
  profileTemplateId = result.id;
  profileTemplateVersion = result.version;
  console.log(JSON.stringify(result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

profile_claim_rule_conditions = {}
profile_claim_rule_conditions['claim'] = 'blueGroups'
profile_claim_rule_conditions['operator'] = 'EQUALS'
profile_claim_rule_conditions['value'] = '\"cloud-docs-dev\"'

profile_claim_rule = {}
profile_claim_rule['name'] = 'My Rule'
profile_claim_rule['realm_name'] = 'https://sdk.test.realm/1234'
profile_claim_rule['type'] = 'Profile-SAML'
profile_claim_rule['expiration'] = 43200
profile_claim_rule['conditions'] = [profile_claim_rule_conditions]

profile = {}
profile['name'] = 'Profile-From-Example-Template'
profile['description'] = 'Trusted profile created from a template'
profile['rules'] = [profile_claim_rule]

create_response = iam_identity_service.create_profile_template(
  name='Example-Profile-Template',
  description='IAM enterprise trusted profile template example',
  account_id=enterprise_account_id,
  profile=profile,
)
profile_template = create_response.get_result()
print('\ncreate_profile_template() response: ', json.dumps(profile_template, indent=2))
Copy to clipboard

Response

Response Body

TrustedProfileTemplateResponse

Response body format for Trusted Profile Template REST requests

TrustedProfileTemplateResponse

Response body format for Trusted Profile Template REST requests.

TrustedProfileTemplateResponse

Response body format for Trusted Profile Template REST requests.

TrustedProfileTemplateResponse

Response body format for Trusted Profile Template REST requests.

TrustedProfileTemplateResponse

Response body format for Trusted Profile Template REST requests.

Status Code

201
Template successfully created
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

Example responses

Status 201

{
  "id": "ProfileTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9",
  "version": 1,
  "account_id": "5bbe28be34524sdbdaa34d37d1f2294a",
  "name": "db admin template",
  "committed": false,
  "profile": {
    "name": "Profile for DB Admins",
    "description": "allows users to admin db instances",
    "rules": [
      {
        "type": "Profile-SAML",
        "realm_name": "${IDP_REALM_NAME}",
        "expiration": 43200,
        "conditions": [
          {
            "claim": "name",
            "operator": "EQUALS",
            "value": "\"My Name\""
          }
        ]
      }
    ],
    "identities": [
      {
        "iam_id": "IBMid-123456789",
        "identifier": "IBMid-123456789",
        "accounts": [
          "5bbe28be34524sdbdaa34d37d1f2294a"
        ]
      }
    ]
  },
  "policy_template_references": [
    {
      "id": "Policy Template-12345",
      "version": "1"
    }
  ],
  "action_controls": {
    "identities": {
      "add": false,
      "remove": true
    },
    "rules": {
      "add": true,
      "remove": true
    },
    "policies": {
      "add": false,
      "remove": true
    }
  },
  "created_at": "2023-03-07T13:55:33:428+0000",
  "created_by_id": "IBMid-12345678901",
  "last_modified_at": "2023-03-07T13:55:33:428+0000",
  "last_modified_by_id": "IBMid-12345678901",
  "entity_tag": "1-2da85a8f1172fc3527378318d3182778",
  "crn": "crn:v1:bluemix:public:iam-identity::a/5bbe28be34524sdbdaa34d37d1f2294a::template:ProfileTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9"
}
Copy to clipboard

Success example

{
  "id": "ProfileTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9",
  "version": 1,
  "account_id": "5bbe28be34524sdbdaa34d37d1f2294a",
  "name": "db admin template",
  "committed": false,
  "profile": {
    "name": "Profile for DB Admins",
    "description": "allows users to admin db instances",
    "rules": [
      {
        "type": "Profile-SAML",
        "realm_name": "${IDP_REALM_NAME}",
        "expiration": 43200,
        "conditions": [
          {
            "claim": "name",
            "operator": "EQUALS",
            "value": "\"My Name\""
          }
        ]
      }
    ],
    "identities": [
      {
        "iam_id": "IBMid-123456789",
        "identifier": "IBMid-123456789",
        "accounts": [
          "5bbe28be34524sdbdaa34d37d1f2294a"
        ]
      }
    ]
  },
  "policy_template_references": [
    {
      "id": "Policy Template-12345",
      "version": "1"
    }
  ],
  "action_controls": {
    "identities": {
      "add": false,
      "remove": true
    },
    "rules": {
      "add": true,
      "remove": true
    },
    "policies": {
      "add": false,
      "remove": true
    }
  },
  "created_at": "2023-03-07T13:55:33:428+0000",
  "created_by_id": "IBMid-12345678901",
  "last_modified_at": "2023-03-07T13:55:33:428+0000",
  "last_modified_by_id": "IBMid-12345678901",
  "entity_tag": "1-2da85a8f1172fc3527378318d3182778",
  "crn": "crn:v1:bluemix:public:iam-identity::a/5bbe28be34524sdbdaa34d37d1f2294a::template:ProfileTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9"
}
Copy to clipboard

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

GET /v1/profile_templates/{template_id}

(iamIdentity *IamIdentityV1) GetLatestProfileTemplateVersion(getLatestProfileTemplateVersionOptions *GetLatestProfileTemplateVersionOptions) (result *TrustedProfileTemplateResponse, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) GetLatestProfileTemplateVersionWithContext(ctx context.Context, getLatestProfileTemplateVersionOptions *GetLatestProfileTemplateVersionOptions) (result *TrustedProfileTemplateResponse, response *core.DetailedResponse, err error)

ServiceCall<TrustedProfileTemplateResponse> getLatestProfileTemplateVersion(GetLatestProfileTemplateVersionOptions getLatestProfileTemplateVersionOptions)
Copy to clipboard

getLatestProfileTemplateVersion(params)

get_latest_profile_template_version(
        self,
        template_id: str,
        *,
        include_history: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.profile-template.read

Request

Instantiate the GetLatestProfileTemplateVersionOptions struct and set the fields to provide parameter values for the GetLatestProfileTemplateVersion method.

Use the GetLatestProfileTemplateVersionOptions.Builder to create a GetLatestProfileTemplateVersionOptions object that contains the parameter values for the getLatestProfileTemplateVersion method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the 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.

Default: false

parameter

WithContext method only

GetLatestProfileTemplateVersionOptions

The GetLatestProfileTemplateVersion options.

GetLatestProfileTemplateVersionOptions

The getLatestProfileTemplateVersion options.

parameters

templateId
Required*
string
ID of the trusted profile template.
includeHistory
boolean
Defines if the entity history is included in the response.

Default: false

parameters

template_id
Required*
str
ID of the trusted profile template.
include_history
bool
Defines if the entity history is included in the response.

Default: false

Example request

curl -X GET "https://iam.cloud.ibm.com/v1/profile_templates/ProfileTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9" --header "Content-Type: application/json" --header "Authorization: Bearer $TOKEN" 
Copy to clipboard

Example request

getOptions := &iamidentityv1.GetLatestProfileTemplateVersionOptions{
  TemplateID: &profileTemplateId,
}

getResponse, response, err := iamIdentityService.GetLatestProfileTemplateVersion(getOptions)

b, _ := json.MarshalIndent(getResponse, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

GetLatestProfileTemplateVersionOptions getOptions = new GetLatestProfileTemplateVersionOptions.Builder()
    .templateId(profileTemplateId)
    .build();

Response<TrustedProfileTemplateResponse> getResponse = service.getLatestProfileTemplateVersion(getOptions).execute();
TrustedProfileTemplateResponse getResult = getResponse.getResult();

System.out.println(getResult);

Example request

const params = {
  templateId: profileTemplateId,
}
try {
  const res = await iamIdentityService.getLatestProfileTemplateVersion(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

get_response = iam_identity_service.get_latest_profile_template_version(template_id=profile_template_id)

profile_template = get_response.get_result()
print('\nget_latest_profile_template_version response: ', json.dumps(profile_template, indent=2))
Copy to clipboard

Response

Response Body

TrustedProfileTemplateResponse

Response body format for Trusted Profile Template REST requests

TrustedProfileTemplateResponse

Response body format for Trusted Profile Template REST requests.

TrustedProfileTemplateResponse

Response body format for Trusted Profile Template REST requests.

TrustedProfileTemplateResponse

Response body format for Trusted Profile Template REST requests.

TrustedProfileTemplateResponse

Response body format for Trusted Profile Template REST requests.

Status Code

200
Successful Template retrieval
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

Example responses

Status 200

{
  "id": "ProfileTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9",
  "version": 1,
  "account_id": "5bbe28be34524sdbdaa34d37d1f2294a",
  "name": "db admin template",
  "committed": false,
  "profile": {
    "name": "Profile for DB Admins",
    "description": "allows users to admin db instances",
    "rules": [
      {
        "type": "Profile-SAML",
        "realm_name": "${IDP_REALM_NAME}",
        "expiration": 43200,
        "conditions": [
          {
            "claim": "name",
            "operator": "EQUALS",
            "value": "\"My Name\""
          }
        ]
      }
    ]
  },
  "policy_template_references": [
    {
      "id": "Policy Template-12345",
      "version": "1"
    }
  ],
  "action_controls": {
    "identities": {
      "add": false,
      "remove": true
    },
    "rules": {
      "add": true,
      "remove": true
    },
    "policies": {
      "add": false,
      "remove": true
    }
  },
  "created_at": "2023-03-07T13:55:33:428+0000",
  "created_by_id": "IBMid-12345678901",
  "last_modified_at": "2023-03-07T13:55:33:428+0000",
  "last_modified_by_id": "IBMid-12345678901",
  "entity_tag": "1-2da85a8f1172fc3527378318d3182778",
  "crn": "crn:v1:bluemix:public:iam-identity::a/5bbe28be34524sdbdaa34d37d1f2294a::template:ProfileTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9"
}
Copy to clipboard

Success example

{
  "id": "ProfileTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9",
  "version": 1,
  "account_id": "5bbe28be34524sdbdaa34d37d1f2294a",
  "name": "db admin template",
  "committed": false,
  "profile": {
    "name": "Profile for DB Admins",
    "description": "allows users to admin db instances",
    "rules": [
      {
        "type": "Profile-SAML",
        "realm_name": "${IDP_REALM_NAME}",
        "expiration": 43200,
        "conditions": [
          {
            "claim": "name",
            "operator": "EQUALS",
            "value": "\"My Name\""
          }
        ]
      }
    ]
  },
  "policy_template_references": [
    {
      "id": "Policy Template-12345",
      "version": "1"
    }
  ],
  "action_controls": {
    "identities": {
      "add": false,
      "remove": true
    },
    "rules": {
      "add": true,
      "remove": true
    },
    "policies": {
      "add": false,
      "remove": true
    }
  },
  "created_at": "2023-03-07T13:55:33:428+0000",
  "created_by_id": "IBMid-12345678901",
  "last_modified_at": "2023-03-07T13:55:33:428+0000",
  "last_modified_by_id": "IBMid-12345678901",
  "entity_tag": "1-2da85a8f1172fc3527378318d3182778",
  "crn": "crn:v1:bluemix:public:iam-identity::a/5bbe28be34524sdbdaa34d37d1f2294a::template:ProfileTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9"
}
Copy to clipboard

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.

DELETE /v1/profile_templates/{template_id}

(iamIdentity *IamIdentityV1) DeleteAllVersionsOfProfileTemplate(deleteAllVersionsOfProfileTemplateOptions *DeleteAllVersionsOfProfileTemplateOptions) (response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) DeleteAllVersionsOfProfileTemplateWithContext(ctx context.Context, deleteAllVersionsOfProfileTemplateOptions *DeleteAllVersionsOfProfileTemplateOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> deleteAllVersionsOfProfileTemplate(DeleteAllVersionsOfProfileTemplateOptions deleteAllVersionsOfProfileTemplateOptions)
Copy to clipboard

deleteAllVersionsOfProfileTemplate(params)

delete_all_versions_of_profile_template(
        self,
        template_id: str,
        **kwargs,
    ) -> DetailedResponse

Authorization

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

iam-identity.profile-template.delete

Request

Instantiate the DeleteAllVersionsOfProfileTemplateOptions struct and set the fields to provide parameter values for the DeleteAllVersionsOfProfileTemplate method.

Use the DeleteAllVersionsOfProfileTemplateOptions.Builder to create a DeleteAllVersionsOfProfileTemplateOptions object that contains the parameter values for the deleteAllVersionsOfProfileTemplate method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

template_id
Required*
string
ID of the trusted profile template

parameter

WithContext method only

DeleteAllVersionsOfProfileTemplateOptions

The DeleteAllVersionsOfProfileTemplate options.

DeleteAllVersionsOfProfileTemplateOptions

The deleteAllVersionsOfProfileTemplate options.

parameters

templateId
Required*
string
ID of the trusted profile template.

parameters

template_id
Required*
str
ID of the trusted profile template.

Example request

curl -X DELETE "https://iam.cloud.ibm.com/v1/profile_templates/ProfileTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9" --header "Content-Type: application/json" --header "Authorization: Bearer $TOKEN" 
Copy to clipboard

Example request

deleteOptions := &iamidentityv1.DeleteAllVersionsOfProfileTemplateOptions{
  TemplateID: &profileTemplateId,
}

response, err := iamIdentityService.DeleteAllVersionsOfProfileTemplate(deleteOptions)

Example request

DeleteAllVersionsOfProfileTemplateOptions deleteTeplateOptions = new DeleteAllVersionsOfProfileTemplateOptions.Builder()
    .templateId(profileTemplateId)
    .build();

Response<Void> deleteResponse = service.deleteAllVersionsOfProfileTemplate(deleteTeplateOptions).execute();

Example request

const params = {
  templateId: profileTemplateId,
}
try {
  const res = await iamIdentityService.deleteAllVersionsOfProfileTemplate(params);
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

delete_response = iam_identity_service.delete_all_versions_of_profile_template(
  template_id=profile_template_id
)

Response

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

GET /v1/profile_templates/{template_id}/versions

(iamIdentity *IamIdentityV1) ListVersionsOfProfileTemplate(listVersionsOfProfileTemplateOptions *ListVersionsOfProfileTemplateOptions) (result *TrustedProfileTemplateList, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) ListVersionsOfProfileTemplateWithContext(ctx context.Context, listVersionsOfProfileTemplateOptions *ListVersionsOfProfileTemplateOptions) (result *TrustedProfileTemplateList, response *core.DetailedResponse, err error)

ServiceCall<TrustedProfileTemplateList> listVersionsOfProfileTemplate(ListVersionsOfProfileTemplateOptions listVersionsOfProfileTemplateOptions)
Copy to clipboard

listVersionsOfProfileTemplate(params)

list_versions_of_profile_template(
        self,
        template_id: str,
        *,
        limit: Optional[str] = None,
        pagetoken: Optional[str] = None,
        sort: Optional[str] = None,
        order: Optional[str] = None,
        include_history: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.profile-template.read

Request

Instantiate the ListVersionsOfProfileTemplateOptions struct and set the fields to provide parameter values for the ListVersionsOfProfileTemplate method.

Use the ListVersionsOfProfileTemplateOptions.Builder to create a ListVersionsOfProfileTemplateOptions object that contains the parameter values for the listVersionsOfProfileTemplate method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

template_id
Required*
string
ID of the trusted profile template

Query Parameters

limit
string
Optional size of a single page.

Possible values: 1 ≤ value ≤ 100
Default: 20
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

Allowable values: [created_at,last_modified_at,name]
Default: created_at
order
string
Optional sort order.

Allowable values: [asc,desc]
Default: asc
include_history
string
Defines if the entity history is included in the response

Default: false

parameter

WithContext method only

ListVersionsOfProfileTemplateOptions

The ListVersionsOfProfileTemplate options.

ListVersionsOfProfileTemplateOptions

The listVersionsOfProfileTemplate options.

parameters

templateId
Required*
string
ID of the trusted profile template.
limit
string
Optional size of a single page.

Possible values: 1 ≤ value ≤ 100
Default: 20
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.

Allowable values: [created_at,last_modified_at,name]
Default: created_at
order
string
Optional sort order.

Allowable values: [asc,desc]
Default: asc
includeHistory
string
Defines if the entity history is included in the response.

Default: false

parameters

template_id
Required*
str
ID of the trusted profile template.
limit
str
Optional size of a single page.

Possible values: 1 ≤ value ≤ 100
Default: 20
pagetoken
str
Optional Prev or Next page token returned from a previous query execution. Default is start with first page.
sort
str
Optional sort property. If specified, the returned templated are sorted according to this property.

Allowable values: [created_at,last_modified_at,name]
Default: created_at
order
str
Optional sort order.

Allowable values: [asc,desc]
Default: asc
include_history
str
Defines if the entity history is included in the response.

Default: false

Example request

curl -X GET "https://iam.cloud.ibm.com/v1/profile_templates/ProfileTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9/versions/" --header "Content-Type: application/json" --header "Authorization: Bearer $TOKEN" 
Copy to clipboard

Example request

listOptions := &iamidentityv1.ListVersionsOfProfileTemplateOptions{
  TemplateID: &profileTemplateId,
}
listResponse, response, err := iamIdentityService.ListVersionsOfProfileTemplate(listOptions)

b, _ := json.MarshalIndent(listResponse, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

ListVersionsOfProfileTemplateOptions listOptions = new ListVersionsOfProfileTemplateOptions.Builder()
    .templateId(profileTemplateId)
    .build();

Response<TrustedProfileTemplateList> listResponse = service.listVersionsOfProfileTemplate(listOptions).execute();
TrustedProfileTemplateList listResult = listResponse.getResult();

System.out.println(listResult);

Example request

const params = {
  templateId: profileTemplateId,
}
try {
  const res = await iamIdentityService.listVersionsOfProfileTemplate(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

list_response = iam_identity_service.list_versions_of_profile_template(template_id=profile_template_id)
profile_template_list = list_response.get_result()
print('\nlist_profile_template_versions response: ', json.dumps(profile_template_list, indent=2))
Copy to clipboard

Response

Response Body

TrustedProfileTemplateList

Status Code

200
Successful Template retrieval
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

Example responses

Status 200

{
  "offset": 0,
  "limit": 20,
  "first": "https://iam.cloud.ibm.com/v1/profile_templates/{template_id}/versions",
  "profile_templates": [
    {
      "id": "ProfileTemplate-2c434aba-38a4-402c-a8a1-c444570b7408",
      "version": 1,
      "account_id": "5bbe28be34524sdbdaa34d37d1f2294a",
      "name": "My new profile template",
      "committed": true,
      "profile": {
        "name": "Profile from template",
        "description": "this is my spanking profile created from a template v1",
        "rules": [
          {
            "type": "Profile-SAML",
            "realm_name": "idp_realm_name",
            "expiration": 43200,
            "conditions": [
              {
                "claim": "name",
                "operator": "EQUALS",
                "value": "\"MyName\""
              }
            ]
          }
        ]
      },
      "policy_template_references": [
        {
          "id": "Policy_Template-ABCD",
          "version": "1"
        },
        {
          "id": "Policy_Template-ABCDe",
          "version": "1"
        }
      ],
      "action_controls": null,
      "identities": {
        "add": false,
        "remove": true
      },
      "rules": {
        "add": true,
        "remove": true
      },
      "policies": {
        "add": false,
        "remove": true
      },
      "created_at": "2023-01-12T13:09:59:761+0000",
      "created_by_id": "IBMid-12345678901",
      "last_modified_at": "2023-02-24T13:48:44:198+0000",
      "last_modified_by_id": "IBMid-12345678901",
      "entity_tag": "6-aa54ac91e59055f80b58da2c5a4c426f",
      "crn": "crn:v1:bluemix:public:iam-identity::a/5bbe28be34524sdbdaa34d37d1f2294a::template:ProfileTemplate-2c434aba-38a4-402c-a8a1-c444570b7408"
    }
  ]
}
Copy to clipboard

Success example

{
  "offset": 0,
  "limit": 20,
  "first": "https://iam.cloud.ibm.com/v1/profile_templates/{template_id}/versions",
  "profile_templates": [
    {
      "id": "ProfileTemplate-2c434aba-38a4-402c-a8a1-c444570b7408",
      "version": 1,
      "account_id": "5bbe28be34524sdbdaa34d37d1f2294a",
      "name": "My new profile template",
      "committed": true,
      "profile": {
        "name": "Profile from template",
        "description": "this is my spanking profile created from a template v1",
        "rules": [
          {
            "type": "Profile-SAML",
            "realm_name": "idp_realm_name",
            "expiration": 43200,
            "conditions": [
              {
                "claim": "name",
                "operator": "EQUALS",
                "value": "\"MyName\""
              }
            ]
          }
        ]
      },
      "policy_template_references": [
        {
          "id": "Policy_Template-ABCD",
          "version": "1"
        },
        {
          "id": "Policy_Template-ABCDe",
          "version": "1"
        }
      ],
      "action_controls": null,
      "identities": {
        "add": false,
        "remove": true
      },
      "rules": {
        "add": true,
        "remove": true
      },
      "policies": {
        "add": false,
        "remove": true
      },
      "created_at": "2023-01-12T13:09:59:761+0000",
      "created_by_id": "IBMid-12345678901",
      "last_modified_at": "2023-02-24T13:48:44:198+0000",
      "last_modified_by_id": "IBMid-12345678901",
      "entity_tag": "6-aa54ac91e59055f80b58da2c5a4c426f",
      "crn": "crn:v1:bluemix:public:iam-identity::a/5bbe28be34524sdbdaa34d37d1f2294a::template:ProfileTemplate-2c434aba-38a4-402c-a8a1-c444570b7408"
    }
  ]
}
Copy to clipboard

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

POST /v1/profile_templates/{template_id}/versions

(iamIdentity *IamIdentityV1) CreateProfileTemplateVersion(createProfileTemplateVersionOptions *CreateProfileTemplateVersionOptions) (result *TrustedProfileTemplateResponse, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) CreateProfileTemplateVersionWithContext(ctx context.Context, createProfileTemplateVersionOptions *CreateProfileTemplateVersionOptions) (result *TrustedProfileTemplateResponse, response *core.DetailedResponse, err error)

ServiceCall<TrustedProfileTemplateResponse> createProfileTemplateVersion(CreateProfileTemplateVersionOptions createProfileTemplateVersionOptions)
Copy to clipboard

createProfileTemplateVersion(params)

create_profile_template_version(
        self,
        template_id: str,
        *,
        account_id: Optional[str] = None,
        name: Optional[str] = None,
        description: Optional[str] = None,
        profile: Optional['TemplateProfileComponentRequest'] = None,
        policy_template_references: Optional[List['PolicyTemplateReference']] = None,
        action_controls: Optional['ActionControls'] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.profile-template.create

Request

Instantiate the CreateProfileTemplateVersionOptions struct and set the fields to provide parameter values for the CreateProfileTemplateVersion method.

Use the CreateProfileTemplateVersionOptions.Builder to create a CreateProfileTemplateVersionOptions object that contains the parameter values for the createProfileTemplateVersion method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

template_id
Required*
string
ID of the trusted profile template

Request Body

Required*

TrustedProfileTemplateRequest

Request to create new version of a Trusted Profile Template

parameter

WithContext method only

CreateProfileTemplateVersionOptions

The CreateProfileTemplateVersion options.

CreateProfileTemplateVersionOptions

The createProfileTemplateVersion options.

parameters

templateId
Required*
string
ID of the trusted profile template.
accountId
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
Input body parameters for the TemplateProfileComponent.
policyTemplateReferences
Existing policy templates that you can reference to assign access in the trusted profile component.
actionControls

parameters

template_id
Required*
str
ID of the trusted profile template.
account_id
str
ID of the account where the template resides.
name
str
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
str
The description of the trusted profile template. Describe the template for enterprise account users.
profile
Input body parameters for the TemplateProfileComponent.
policy_template_references
Existing policy templates that you can reference to assign access in the trusted profile component.
action_controls

Example request

curl -X POST "https://iam.cloud.ibm.com/v1/profile_templates/{template_id}/versions/" --header "Content-Type: application/json" --header "Authorization: Bearer $TOKEN" --data '{
    "account_id": "5bbe28be34524sdbdaa34d37d1f2294a",
    "name": "db admin template",
    "profile": {
        "name": "Profile for DB Admins",
        "description": "allows users to admin db instances",
        "rules": [
            {
                "type": "Profile",
                "realm_name": "${IDP_REALM_NAME}",
                "expiration": 43200,
                "conditions": [
                    {
                        "claim": "name",
                        "operator": "EQUALS",
                        "value": "\"My Name\""
                    }
                ]
            }
        ]
    },
    "policy_template_references": [
        {
            "id": "Policy Template-12345",
            "version": 1
        }
    ]
}'
Copy to clipboard

Example request

profileClaimRuleConditions := new(iamidentityv1.ProfileClaimRuleConditions)
profileClaimRuleConditions.Claim = core.StringPtr("blueGroups")
profileClaimRuleConditions.Operator = core.StringPtr("EQUALS")
profileClaimRuleConditions.Value = core.StringPtr("\"cloud-docs-dev\"")

profileTemplateClaimRule := new(iamidentityv1.TrustedProfileTemplateClaimRule)
profileTemplateClaimRule.Name = core.StringPtr("My Rule")
profileTemplateClaimRule.RealmName = &realmName
profileTemplateClaimRule.Type = &claimRuleType
profileTemplateClaimRule.Expiration = core.Int64Ptr(int64(43200))
profileTemplateClaimRule.Conditions = []iamidentityv1.ProfileClaimRuleConditions{*profileClaimRuleConditions}

profile := new(iamidentityv1.TemplateProfileComponentRequest)
profile.Name = &profileTemplateProfileName
profile.Description = core.StringPtr("Example Profile created from Profile Template - new version")
profile.Rules = []iamidentityv1.TrustedProfileTemplateClaimRule{*profileTemplateClaimRule}

createOptions := &iamidentityv1.CreateProfileTemplateVersionOptions{
  Name:        &profileTemplateName,
  Description: core.StringPtr("Example Profile Template - new version"),
  AccountID:   &enterpriseAccountID,
  TemplateID:  &profileTemplateId,
  Profile:     profile,
}

createResponse, response, err := iamIdentityService.CreateProfileTemplateVersion(createOptions)

b, _ := json.MarshalIndent(createResponse, "", "  ")
fmt.Println(string(b))

// save the new version to be used in subsequent calls
profileTemplateVersion = *createResponse.Version
Copy to clipboard

Example request

ProfileClaimRuleConditions condition = new ProfileClaimRuleConditions.Builder()
    .claim("blueGroups")
    .operator("EQUALS")
    .value("\"cloud-docs-dev\"")
    .build();
List<ProfileClaimRuleConditions> conditions = new ArrayList<>();
conditions.add(condition);

TrustedProfileTemplateClaimRule claimRule = new TrustedProfileTemplateClaimRule.Builder()
    .name("My Rule")
    .realmName(realmName)
    .type(claimRuleType)
    .expiration(43200)
    .conditions(conditions)
    .build();

List<String> accounts = new ArrayList<String>();
accounts.add(enterpriseAccountId);
ProfileIdentityRequest profileIdentity = new ProfileIdentityRequest.Builder()
    .identifier(iamId)
    .accounts(accounts)
    .type("user")
    .description("Identity description")
    .build();
List<ProfileIdentityRequest> identities = new ArrayList<ProfileIdentityRequest>();
identities.add(profileIdentity);

TemplateProfileComponentRequest profile = new TemplateProfileComponentRequest.Builder()
    .addRules(claimRule)
    .name(profileTemplateProfileName)
    .description("Trusted profile created from a template - new version")
    .identities(identities)
    .build();

CreateProfileTemplateVersionOptions createOptions = new CreateProfileTemplateVersionOptions.Builder()
    .accountId(enterpriseAccountId)
    .templateId(profileTemplateId)
    .name(profileTemplateName)
    .description("IAM enterprise trusted profile template example - new version")
    .profile(profile)
    .build();

Response<TrustedProfileTemplateResponse> createResponse = service.createProfileTemplateVersion(createOptions).execute();
TrustedProfileTemplateResponse createResult = createResponse.getResult();

// Save the version for use by other test methods.
profileTemplateVersion = createResult.getVersion().longValue();
System.out.println(createResult);
Copy to clipboard

Example request

 const condition = {
   claim: "blueGroups",
   operator: "EQUALS",
   value: "\"cloud-docs-dev\"",
 }
 const claimRule = {
    name: "My Rule",
    realm_name: realmName,
    type: 'Profile-SAML',
    expiration: 43200,
    conditions: [condition],
 }
 const identity = {
   identifier: iamId,
   accounts: [enterpriseAccountId],
   type: "user",
   description: "Identity description",
}
const profile = {
   rules: [claimRule],
   name: "Profile-From-Example-Template",
   description: "Trusted profile created from a template - new version",
   identities: [identity],
 }
 const templateParams = {
   templateId: profileTemplateId,
   name: "Example-Profile-Template",
   description: "IAM enterprise trusted profile template example - new version",
   accountId: enterpriseAccountId,
   profile: profile,
 }
  
 try {
   const res = await iamIdentityService.createProfileTemplateVersion(templateParams);
   const { result } = res;
   profileTemplateVersion = result.version;
   console.log(JSON.stringify(result, null, 2));
 } catch (err) {
   console.warn(err);
 }
Copy to clipboard

Example request

profile_claim_rule_conditions = {}
profile_claim_rule_conditions['claim'] = 'blueGroups'
profile_claim_rule_conditions['operator'] = 'EQUALS'
profile_claim_rule_conditions['value'] = '\"cloud-docs-dev\"'

profile_claim_rule = {}
profile_claim_rule['name'] = 'My Rule'
profile_claim_rule['realm_name'] = 'https://sdk.test.realm/1234'
profile_claim_rule['type'] = 'Profile-SAML'
profile_claim_rule['expiration'] = 43200
profile_claim_rule['conditions'] = [profile_claim_rule_conditions]

profile_identity = {}
profile_identity['identifier'] = iam_id
profile_identity['accounts'] = [enterprise_account_id]
profile_identity['type'] = 'user'
profile_identity['description'] = 'Identity description'

profile = {}
profile['name'] = 'Profile-From-Example-Template'
profile['description'] = 'Trusted profile created from a template - new version'
profile['rules'] = [profile_claim_rule]
profile['identities'] = [profile_identity]

create_response = iam_identity_service.create_profile_template_version(
  template_id=profile_template_id,
  name='Example-Profile-Template',
  description='IAM enterprise trusted profile template example - new version',
  account_id=enterprise_account_id,
  profile=profile,
)
profile_template = create_response.get_result()
print('\ncreate_profile_template_version() response: ', json.dumps(profile_template, indent=2))
Copy to clipboard

Response

Response Body

TrustedProfileTemplateResponse

Response body format for Trusted Profile Template REST requests

TrustedProfileTemplateResponse

Response body format for Trusted Profile Template REST requests.

TrustedProfileTemplateResponse

Response body format for Trusted Profile Template REST requests.

TrustedProfileTemplateResponse

Response body format for Trusted Profile Template REST requests.

TrustedProfileTemplateResponse

Response body format for Trusted Profile Template REST requests.

Status Code

201
Template version created successfully
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

Example responses

Status 201

{
  "id": "ProfileTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9",
  "version": 2,
  "account_id": "5bbe28be34524sdbdaa34d37d1f2294a",
  "name": "db admin template",
  "committed": false,
  "profile": {
    "name": "Profile for DB Admins",
    "description": "allows users to admin db instances",
    "rules": [
      {
        "type": "Profile-SAML",
        "realm_name": "${IDP_REALM_NAME}",
        "expiration": 43200,
        "conditions": [
          {
            "claim": "name",
            "operator": "EQUALS",
            "value": "\"My Name\""
          }
        ]
      }
    ]
  },
  "policy_template_references": [
    {
      "id": "Policy Template-12345",
      "version": "1"
    }
  ],
  "action_controls": {
    "identities": {
      "add": false,
      "remove": true
    },
    "rules": {
      "add": true,
      "remove": true
    },
    "policies": {
      "add": false,
      "remove": true
    }
  },
  "created_at": "2023-03-07T13:55:33:428+0000",
  "created_by_id": "IBMid-12345678901",
  "last_modified_at": "2023-03-07T15:05:00:000+0000",
  "last_modified_by_id": "IBMid-12345678901",
  "entity_tag": "1-2da85a8f1172fc3527378318d3182778",
  "crn": "crn:v1:bluemix:public:iam-identity::a/5bbe28be34524sdbdaa34d37d1f2294a::template:ProfileTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9"
}
Copy to clipboard

Success example

{
  "id": "ProfileTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9",
  "version": 2,
  "account_id": "5bbe28be34524sdbdaa34d37d1f2294a",
  "name": "db admin template",
  "committed": false,
  "profile": {
    "name": "Profile for DB Admins",
    "description": "allows users to admin db instances",
    "rules": [
      {
        "type": "Profile-SAML",
        "realm_name": "${IDP_REALM_NAME}",
        "expiration": 43200,
        "conditions": [
          {
            "claim": "name",
            "operator": "EQUALS",
            "value": "\"My Name\""
          }
        ]
      }
    ]
  },
  "policy_template_references": [
    {
      "id": "Policy Template-12345",
      "version": "1"
    }
  ],
  "action_controls": {
    "identities": {
      "add": false,
      "remove": true
    },
    "rules": {
      "add": true,
      "remove": true
    },
    "policies": {
      "add": false,
      "remove": true
    }
  },
  "created_at": "2023-03-07T13:55:33:428+0000",
  "created_by_id": "IBMid-12345678901",
  "last_modified_at": "2023-03-07T15:05:00:000+0000",
  "last_modified_by_id": "IBMid-12345678901",
  "entity_tag": "1-2da85a8f1172fc3527378318d3182778",
  "crn": "crn:v1:bluemix:public:iam-identity::a/5bbe28be34524sdbdaa34d37d1f2294a::template:ProfileTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9"
}
Copy to clipboard

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

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

(iamIdentity *IamIdentityV1) GetProfileTemplateVersion(getProfileTemplateVersionOptions *GetProfileTemplateVersionOptions) (result *TrustedProfileTemplateResponse, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) GetProfileTemplateVersionWithContext(ctx context.Context, getProfileTemplateVersionOptions *GetProfileTemplateVersionOptions) (result *TrustedProfileTemplateResponse, response *core.DetailedResponse, err error)

ServiceCall<TrustedProfileTemplateResponse> getProfileTemplateVersion(GetProfileTemplateVersionOptions getProfileTemplateVersionOptions)
Copy to clipboard

getProfileTemplateVersion(params)

get_profile_template_version(
        self,
        template_id: str,
        version: str,
        *,
        include_history: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.profile-template.read

Request

Instantiate the GetProfileTemplateVersionOptions struct and set the fields to provide parameter values for the GetProfileTemplateVersion method.

Use the GetProfileTemplateVersionOptions.Builder to create a GetProfileTemplateVersionOptions object that contains the parameter values for the getProfileTemplateVersion method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the 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

Default: false

parameter

WithContext method only

GetProfileTemplateVersionOptions

The GetProfileTemplateVersion options.

GetProfileTemplateVersionOptions

The getProfileTemplateVersion options.

parameters

templateId
Required*
string
ID of the trusted profile template.
version
Required*
string
Version of the Profile Template.
includeHistory
boolean
Defines if the entity history is included in the response.

Default: false

parameters

template_id
Required*
str
ID of the trusted profile template.
version
Required*
str
Version of the Profile Template.
include_history
bool
Defines if the entity history is included in the response.

Default: false

Example request

curl -X GET "https://iam.cloud.ibm.com/v1/profile_templates/{template_id}/versions/{version}" --header "Content-Type: application/json" --header "Authorization: Bearer $TOKEN" 
Copy to clipboard

Example request

getOptions := &iamidentityv1.GetProfileTemplateVersionOptions{
  TemplateID: &profileTemplateId,
  Version:    core.StringPtr(strconv.FormatInt(profileTemplateVersion, 10)),
}
getResponse, response, err := iamIdentityService.GetProfileTemplateVersion(getOptions)

b, _ := json.MarshalIndent(getResponse, "", "  ")
fmt.Println(string(b))

// Grab the Etag value from the response for use in the update operation
profileTemplateEtag = response.GetHeaders().Get("Etag")
Copy to clipboard

Example request

GetProfileTemplateVersionOptions getProfileTemplateOptions = new GetProfileTemplateVersionOptions.Builder()
    .templateId(profileTemplateId)
    .version(Long.toString(profileTemplateVersion))
    .build();

Response<TrustedProfileTemplateResponse> response = service.getProfileTemplateVersion(getProfileTemplateOptions).execute();
TrustedProfileTemplateResponse profileTemplateResult = response.getResult();

// Grab the Etag value from the response for use in the update operation.
profileTemplateEtag = response.getHeaders().values("Etag").get(0);

System.out.println(profileTemplateResult);
Copy to clipboard

Example request

const params = {
  templateId: profileTemplateId,
  version: profileTemplateVersion,
}
try {
  const res = await iamIdentityService.getProfileTemplateVersion(params);
  profileTemplateEtag = res.headers.etag;
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

get_response = iam_identity_service.get_profile_template_version(
  template_id=profile_template_id, version=str(profile_template_version)
)
profile_template = get_response.get_result()
print('\nget_profile_template response: ', json.dumps(profile_template, indent=2))
Copy to clipboard

Response

Response Body

TrustedProfileTemplateResponse

Response body format for Trusted Profile Template REST requests

TrustedProfileTemplateResponse

Response body format for Trusted Profile Template REST requests.

TrustedProfileTemplateResponse

Response body format for Trusted Profile Template REST requests.

TrustedProfileTemplateResponse

Response body format for Trusted Profile Template REST requests.

TrustedProfileTemplateResponse

Response body format for Trusted Profile Template REST requests.

Status Code

200
Successful Template retrieval
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

Example responses

Status 200

{
  "id": "ProfileTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9",
  "version": 1,
  "account_id": "5bbe28be34524sdbdaa34d37d1f2294a",
  "name": "db admin template",
  "committed": false,
  "profile": {
    "name": "Profile for DB Admins",
    "description": "allows users to admin db instances",
    "rules": [
      {
        "type": "Profile-SAML",
        "realm_name": "${IDP_REALM_NAME}",
        "expiration": 43200,
        "conditions": [
          {
            "claim": "name",
            "operator": "EQUALS",
            "value": "\"My Name\""
          }
        ]
      }
    ]
  },
  "policy_template_references": [
    {
      "id": "Policy Template-12345",
      "version": "1"
    }
  ],
  "action_controls": {
    "identities": {
      "add": false,
      "remove": true
    },
    "rules": {
      "add": true,
      "remove": true
    },
    "policies": {
      "add": false,
      "remove": true
    }
  },
  "created_at": "2023-03-07T13:55:33:428+0000",
  "created_by_id": "IBMid-12345678901",
  "last_modified_at": "2023-03-07T13:55:33:428+0000",
  "last_modified_by_id": "IBMid-12345678901",
  "entity_tag": "1-2da85a8f1172fc3527378318d3182778",
  "crn": "crn:v1:bluemix:public:iam-identity::a/5bbe28be34524sdbdaa34d37d1f2294a::template:ProfileTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9"
}
Copy to clipboard

Success example

{
  "id": "ProfileTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9",
  "version": 1,
  "account_id": "5bbe28be34524sdbdaa34d37d1f2294a",
  "name": "db admin template",
  "committed": false,
  "profile": {
    "name": "Profile for DB Admins",
    "description": "allows users to admin db instances",
    "rules": [
      {
        "type": "Profile-SAML",
        "realm_name": "${IDP_REALM_NAME}",
        "expiration": 43200,
        "conditions": [
          {
            "claim": "name",
            "operator": "EQUALS",
            "value": "\"My Name\""
          }
        ]
      }
    ]
  },
  "policy_template_references": [
    {
      "id": "Policy Template-12345",
      "version": "1"
    }
  ],
  "action_controls": {
    "identities": {
      "add": false,
      "remove": true
    },
    "rules": {
      "add": true,
      "remove": true
    },
    "policies": {
      "add": false,
      "remove": true
    }
  },
  "created_at": "2023-03-07T13:55:33:428+0000",
  "created_by_id": "IBMid-12345678901",
  "last_modified_at": "2023-03-07T13:55:33:428+0000",
  "last_modified_by_id": "IBMid-12345678901",
  "entity_tag": "1-2da85a8f1172fc3527378318d3182778",
  "crn": "crn:v1:bluemix:public:iam-identity::a/5bbe28be34524sdbdaa34d37d1f2294a::template:ProfileTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9"
}
Copy to clipboard

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

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

(iamIdentity *IamIdentityV1) UpdateProfileTemplateVersion(updateProfileTemplateVersionOptions *UpdateProfileTemplateVersionOptions) (result *TrustedProfileTemplateResponse, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) UpdateProfileTemplateVersionWithContext(ctx context.Context, updateProfileTemplateVersionOptions *UpdateProfileTemplateVersionOptions) (result *TrustedProfileTemplateResponse, response *core.DetailedResponse, err error)

ServiceCall<TrustedProfileTemplateResponse> updateProfileTemplateVersion(UpdateProfileTemplateVersionOptions updateProfileTemplateVersionOptions)
Copy to clipboard

updateProfileTemplateVersion(params)

update_profile_template_version(
        self,
        if_match: str,
        template_id: str,
        version: str,
        *,
        account_id: Optional[str] = None,
        name: Optional[str] = None,
        description: Optional[str] = None,
        profile: Optional['TemplateProfileComponentRequest'] = None,
        policy_template_references: Optional[List['PolicyTemplateReference']] = None,
        action_controls: Optional['ActionControls'] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.profile-template.update

Request

Instantiate the UpdateProfileTemplateVersionOptions struct and set the fields to provide parameter values for the UpdateProfileTemplateVersion method.

Use the UpdateProfileTemplateVersionOptions.Builder to create a UpdateProfileTemplateVersionOptions object that contains the parameter values for the updateProfileTemplateVersion method.

Custom Headers

If-Match
Required*
string
Entity tag of the Template to be updated. Specify the tag that you retrieved when reading the Profile Template. This value helps identifying parallel usage of this API. Pass * to indicate to update any version available. This might result in stale updates.
Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

template_id
Required*
string
ID of the trusted profile template
version
Required*
string
Version of the Profile Template

Request Body

Required*

TrustedProfileTemplateRequest

Request to create a trusted profile template.

parameter

WithContext method only

UpdateProfileTemplateVersionOptions

The UpdateProfileTemplateVersion options.

UpdateProfileTemplateVersionOptions

The updateProfileTemplateVersion options.

parameters

ifMatch
Required*
string
Entity tag of the Template to be updated. Specify the tag that you retrieved when reading the Profile Template. This value helps identifying parallel usage of this API. Pass * to indicate to update any version available. This might result in stale updates.
templateId
Required*
string
ID of the trusted profile template.
version
Required*
string
Version of the Profile Template.
accountId
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
Input body parameters for the TemplateProfileComponent.
policyTemplateReferences
Existing policy templates that you can reference to assign access in the trusted profile component.
actionControls

parameters

if_match
Required*
str
Entity tag of the Template to be updated. Specify the tag that you retrieved when reading the Profile Template. This value helps identifying parallel usage of this API. Pass * to indicate to update any version available. This might result in stale updates.
template_id
Required*
str
ID of the trusted profile template.
version
Required*
str
Version of the Profile Template.
account_id
str
ID of the account where the template resides.
name
str
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
str
The description of the trusted profile template. Describe the template for enterprise account users.
profile
Input body parameters for the TemplateProfileComponent.
policy_template_references
Existing policy templates that you can reference to assign access in the trusted profile component.
action_controls

Example request

curl -X PUT "https://iam.cloud.ibm.com/v1/profile_templates/{template_id}/versions/{version}" --header "Content-Type: application/json" --header "Authorization: Bearer $TOKEN" --header "If-Match: <value of etag header from GET request>" --data '{
    "account_id": "5bbe28be34524sdbdaa34d37d1f2294a",
    "name": "db admin template",
    "profile": {
        "name": "Profile for DB Admins",
        "description": "allows users to admin db instances",
        "rules": [
            {
                "type": "Profile",
                "realm_name": "${IDP_REALM_NAME}",
                "expiration": 43200,
                "conditions": [
                    {
                        "claim": "name",
                        "operator": "EQUALS",
                        "value": "\"My Name\""
                    }
                ]
            }
        ]
    },
    "policy_template_references": [
        {
            "id": "Policy Template-12345",
            "version": 1
        }
    ]
}'
Copy to clipboard

Example request

updateOptions := &iamidentityv1.UpdateProfileTemplateVersionOptions{
  AccountID:   &enterpriseAccountID,
  TemplateID:  &profileTemplateId,
  Version:     core.StringPtr(strconv.FormatInt(profileTemplateVersion, 10)),
  IfMatch:     &profileTemplateEtag,
  Name:        &profileTemplateName,
  Description: core.StringPtr("Example Profile Template - updated"),
}
updateResponse, response, err := iamIdentityService.UpdateProfileTemplateVersion(updateOptions)

b, _ := json.MarshalIndent(updateResponse, "", "  ")
fmt.Println(string(b))

// Grab the Etag value from the response for use in the update operation.
profileTemplateEtag = response.GetHeaders().Get("Etag")
Copy to clipboard

Example request

UpdateProfileTemplateVersionOptions updateOptions = new UpdateProfileTemplateVersionOptions.Builder()
    .accountId(enterpriseAccountId)
    .templateId(profileTemplateId)
    .version(Long.toString(profileTemplateVersion))
    .ifMatch(profileTemplateEtag)
    .name(profileTemplateName)
    .description("IAM enterprise trusted profile template example - updated")
    .build();

Response<TrustedProfileTemplateResponse> updateResponse = service.updateProfileTemplateVersion(updateOptions).execute();
TrustedProfileTemplateResponse updateResult = updateResponse.getResult();

// Grab the Etag value from the response for use in the update operation.
profileTemplateEtag = updateResponse.getHeaders().values("Etag").get(0);

System.out.println(updateResult);
Copy to clipboard

Example request

const params = {
  accountId: enterpriseAccountId,
  templateId: profileTemplateId,
  version: profileTemplateVersion,
  ifMatch: profileTemplateEtag,
  name: "Example-Profile-Template",
  description: "IAM enterprise trusted profile template example - updated",
}
try {
  const res = await iamIdentityService.updateProfileTemplateVersion(params);
  profileTemplateEtag = res.headers.etag;
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

update_response = iam_identity_service.update_profile_template_version(
  account_id=enterprise_account_id,
  template_id=profile_template_id,
  version=str(profile_template_version),
  if_match=profile_template_etag,
  name='Example-Profile-Template',
  description='IAM enterprise trusted profile template example - updated',
)
profile_template = update_response.get_result()
print('\nupdate_profile_template() response: ', json.dumps(profile_template, indent=2))
Copy to clipboard

Response

Response Body

TrustedProfileTemplateResponse

Response body format for Trusted Profile Template REST requests

TrustedProfileTemplateResponse

Response body format for Trusted Profile Template REST requests.

TrustedProfileTemplateResponse

Response body format for Trusted Profile Template REST requests.

TrustedProfileTemplateResponse

Response body format for Trusted Profile Template REST requests.

TrustedProfileTemplateResponse

Response body format for Trusted Profile Template REST requests.

Status Code

200
Successful updated template
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

Example responses

Status 200

{
  "id": "ProfileTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9",
  "version": 1,
  "account_id": "5bbe28be34524sdbdaa34d37d1f2294a",
  "name": "db admin template",
  "committed": false,
  "profile": {
    "name": "Profile for DB Admins",
    "description": "allows users to admin db instances",
    "rules": [
      {
        "type": "Profile-SAML",
        "realm_name": "${IDP_REALM_NAME}",
        "expiration": 43200,
        "conditions": [
          {
            "claim": "name",
            "operator": "EQUALS",
            "value": "\"My Name\""
          }
        ]
      }
    ]
  },
  "policy_template_references": [
    {
      "id": "Policy Template-12345",
      "version": "1"
    }
  ],
  "action_controls": {
    "identities": {
      "add": false,
      "remove": true
    },
    "rules": {
      "add": true,
      "remove": true
    },
    "policies": {
      "add": false,
      "remove": true
    }
  },
  "created_at": "2023-03-07T13:55:33:428+0000",
  "created_by_id": "IBMid-12345678901",
  "last_modified_at": "2023-03-07T13:55:33:428+0000",
  "last_modified_by_id": "IBMid-12345678901",
  "entity_tag": "1-2da85a8f1172fc3527378318d3182778",
  "crn": "crn:v1:bluemix:public:iam-identity::a/5bbe28be34524sdbdaa34d37d1f2294a::template:ProfileTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9"
}
Copy to clipboard

Success example

{
  "id": "ProfileTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9",
  "version": 1,
  "account_id": "5bbe28be34524sdbdaa34d37d1f2294a",
  "name": "db admin template",
  "committed": false,
  "profile": {
    "name": "Profile for DB Admins",
    "description": "allows users to admin db instances",
    "rules": [
      {
        "type": "Profile-SAML",
        "realm_name": "${IDP_REALM_NAME}",
        "expiration": 43200,
        "conditions": [
          {
            "claim": "name",
            "operator": "EQUALS",
            "value": "\"My Name\""
          }
        ]
      }
    ]
  },
  "policy_template_references": [
    {
      "id": "Policy Template-12345",
      "version": "1"
    }
  ],
  "action_controls": {
    "identities": {
      "add": false,
      "remove": true
    },
    "rules": {
      "add": true,
      "remove": true
    },
    "policies": {
      "add": false,
      "remove": true
    }
  },
  "created_at": "2023-03-07T13:55:33:428+0000",
  "created_by_id": "IBMid-12345678901",
  "last_modified_at": "2023-03-07T13:55:33:428+0000",
  "last_modified_by_id": "IBMid-12345678901",
  "entity_tag": "1-2da85a8f1172fc3527378318d3182778",
  "crn": "crn:v1:bluemix:public:iam-identity::a/5bbe28be34524sdbdaa34d37d1f2294a::template:ProfileTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9"
}
Copy to clipboard

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.

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

(iamIdentity *IamIdentityV1) DeleteProfileTemplateVersion(deleteProfileTemplateVersionOptions *DeleteProfileTemplateVersionOptions) (response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) DeleteProfileTemplateVersionWithContext(ctx context.Context, deleteProfileTemplateVersionOptions *DeleteProfileTemplateVersionOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> deleteProfileTemplateVersion(DeleteProfileTemplateVersionOptions deleteProfileTemplateVersionOptions)
Copy to clipboard

deleteProfileTemplateVersion(params)

delete_profile_template_version(
        self,
        template_id: str,
        version: str,
        **kwargs,
    ) -> DetailedResponse

Authorization

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

iam-identity.profile-template.delete

Request

Instantiate the DeleteProfileTemplateVersionOptions struct and set the fields to provide parameter values for the DeleteProfileTemplateVersion method.

Use the DeleteProfileTemplateVersionOptions.Builder to create a DeleteProfileTemplateVersionOptions object that contains the parameter values for the deleteProfileTemplateVersion method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

template_id
Required*
string
ID of the trusted profile template
version
Required*
string
Version of the Profile Template

parameter

WithContext method only

DeleteProfileTemplateVersionOptions

The DeleteProfileTemplateVersion options.

DeleteProfileTemplateVersionOptions

The deleteProfileTemplateVersion options.

parameters

templateId
Required*
string
ID of the trusted profile template.
version
Required*
string
Version of the Profile Template.

parameters

template_id
Required*
str
ID of the trusted profile template.
version
Required*
str
Version of the Profile Template.

Example request

curl -X DELETE "https://iam.cloud.ibm.com/v1/profile_templates/{template_id}/versions/{version}" --header "Content-Type: application/json" --header "Authorization: Bearer $TOKEN" 
Copy to clipboard

Example request

deleteOptions := &iamidentityv1.DeleteProfileTemplateVersionOptions{
  TemplateID: &profileTemplateId,
  Version:    core.StringPtr("1"),
}

response, err := iamIdentityService.DeleteProfileTemplateVersion(deleteOptions)

Example request

DeleteProfileTemplateVersionOptions deleteOptions = new DeleteProfileTemplateVersionOptions.Builder()
    .templateId(profileTemplateId)
    .version("1")
    .build();

Response<Void> deleteResponse = service.deleteProfileTemplateVersion(deleteOptions).execute();

Example request

const params = {
  templateId: profileTemplateId,
  version: 1,
}
try {
  const res = await iamIdentityService.deleteProfileTemplateVersion(params);
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

delete_response = iam_identity_service.delete_profile_template_version(
  template_id=profile_template_id, version='1'
)

Response

Status Code

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

No Sample Response

This method does not specify any sample responses.

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.

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

(iamIdentity *IamIdentityV1) CommitProfileTemplate(commitProfileTemplateOptions *CommitProfileTemplateOptions) (response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) CommitProfileTemplateWithContext(ctx context.Context, commitProfileTemplateOptions *CommitProfileTemplateOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> commitProfileTemplate(CommitProfileTemplateOptions commitProfileTemplateOptions)
Copy to clipboard

commitProfileTemplate(params)

commit_profile_template(
        self,
        template_id: str,
        version: str,
        **kwargs,
    ) -> DetailedResponse

Authorization

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

iam-identity.profile-template.update

Request

Instantiate the CommitProfileTemplateOptions struct and set the fields to provide parameter values for the CommitProfileTemplate method.

Use the CommitProfileTemplateOptions.Builder to create a CommitProfileTemplateOptions object that contains the parameter values for the commitProfileTemplate method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

template_id
Required*
string
ID of the trusted profile template
version
Required*
string
Version of the Profile Template

parameter

WithContext method only

CommitProfileTemplateOptions

The CommitProfileTemplate options.

CommitProfileTemplateOptions

The commitProfileTemplate options.

parameters

templateId
Required*
string
ID of the trusted profile template.
version
Required*
string
Version of the Profile Template.

parameters

template_id
Required*
str
ID of the trusted profile template.
version
Required*
str
Version of the Profile Template.

Example request

curl -X POST "https://iam.cloud.ibm.com/v1/profile_templates/{template_id}/versions/{version}/commit" --header "Content-Type: application/json" --header "Authorization: Bearer $TOKEN" 
Copy to clipboard

Example request

commitOptions := &iamidentityv1.CommitProfileTemplateOptions{
  TemplateID: &profileTemplateId,
  Version:    core.StringPtr(strconv.FormatInt(profileTemplateVersion, 10)),
}

response, err := iamIdentityService.CommitProfileTemplate(commitOptions)

Example request

CommitProfileTemplateOptions commitOptions = new CommitProfileTemplateOptions.Builder()
    .templateId(profileTemplateId)
    .version(Long.toString(profileTemplateVersion))
    .build();

Response<Void> commitResponse = service.commitProfileTemplate(commitOptions).execute();

Example request

const commitParams = {
  templateId: profileTemplateId,
  version: profileTemplateVersion,
}
try {
  const res = await iamIdentityService.commitProfileTemplate(commitParams);
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

commit_response = iam_identity_service.commit_profile_template(
  template_id=profile_template_id, version=str(profile_template_version)
)

Response

Status Code

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

No Sample Response

This method does not specify any sample responses.

List account settings templates in an enterprise account

List account settings templates in an enterprise account.

GET /v1/account_settings_templates

(iamIdentity *IamIdentityV1) ListAccountSettingsTemplates(listAccountSettingsTemplatesOptions *ListAccountSettingsTemplatesOptions) (result *AccountSettingsTemplateList, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) ListAccountSettingsTemplatesWithContext(ctx context.Context, listAccountSettingsTemplatesOptions *ListAccountSettingsTemplatesOptions) (result *AccountSettingsTemplateList, response *core.DetailedResponse, err error)

ServiceCall<AccountSettingsTemplateList> listAccountSettingsTemplates(ListAccountSettingsTemplatesOptions listAccountSettingsTemplatesOptions)
Copy to clipboard

listAccountSettingsTemplates(params)

list_account_settings_templates(
        self,
        *,
        account_id: Optional[str] = None,
        limit: Optional[str] = None,
        pagetoken: Optional[str] = None,
        sort: Optional[str] = None,
        order: Optional[str] = None,
        include_history: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.account-settings-template.read

Request

Instantiate the ListAccountSettingsTemplatesOptions struct and set the fields to provide parameter values for the ListAccountSettingsTemplates method.

Use the ListAccountSettingsTemplatesOptions.Builder to create a ListAccountSettingsTemplatesOptions object that contains the parameter values for the listAccountSettingsTemplates method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

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.

Possible values: 1 ≤ value ≤ 100
Default: 20
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

Allowable values: [created_at,last_modified_at,name]
Default: created_at
order
string
Optional sort order.

Allowable values: [asc,desc]
Default: asc
include_history
string
Defines if the entity history is included in the response

Default: false

parameter

WithContext method only

ListAccountSettingsTemplatesOptions

The ListAccountSettingsTemplates options.

ListAccountSettingsTemplatesOptions

The listAccountSettingsTemplates options.

parameters

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

Possible values: 1 ≤ value ≤ 100
Default: 20
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.

Allowable values: [created_at,last_modified_at,name]
Default: created_at
order
string
Optional sort order.

Allowable values: [asc,desc]
Default: asc
includeHistory
string
Defines if the entity history is included in the response.

Default: false

parameters

account_id
str
Account ID of the account settings templates to query. This parameter is required unless using a pagetoken.
limit
str
Optional size of a single page.

Possible values: 1 ≤ value ≤ 100
Default: 20
pagetoken
str
Optional Prev or Next page token returned from a previous query execution. Default is start with first page.
sort
str
Optional sort property. If specified, the returned templated are sorted according to this property.

Allowable values: [created_at,last_modified_at,name]
Default: created_at
order
str
Optional sort order.

Allowable values: [asc,desc]
Default: asc
include_history
str
Defines if the entity history is included in the response.

Default: false

Example request

curl -X GET "https://iam.cloud.ibm.com/v1/account_settings_templates?account_id=5bbe28be34524sdbdaa34d37d1f2294a" --header "Content-Type: application/json" --header "Authorization: Bearer $TOKEN" 
Copy to clipboard

Example request

listOptions := &iamidentityv1.ListAccountSettingsTemplatesOptions{
  AccountID: &enterpriseAccountID,
}

listResponse, response, err := iamIdentityService.ListAccountSettingsTemplates(listOptions)

b, _ := json.MarshalIndent(listResponse, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

ListAccountSettingsTemplatesOptions listOptions = new ListAccountSettingsTemplatesOptions.Builder()
    .accountId(enterpriseAccountId)
    .build();

Response<AccountSettingsTemplateList> response = service.listAccountSettingsTemplates(listOptions).execute();
AccountSettingsTemplateList result = response.getResult();

System.out.println(result);

Example request

const params = {
  accountId: enterpriseAccountId,
}
try {
  const res = await iamIdentityService.listAccountSettingsTemplates(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

list_response = iam_identity_service.list_account_settings_templates(account_id=enterprise_account_id)
account_settings_template_list = list_response.get_result()
print('\nlist_account_settings_templates response: ', json.dumps(account_settings_template_list, indent=2))
Copy to clipboard

Response

Response Body

AccountSettingsTemplateList

Status Code

200
Successful Template retrieval
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

Example responses

Status 200

{
  "offset": 0,
  "limit": 20,
  "first": "https://iam.cloud.ibm.com/v1/account_settings_templates?account_id=5bbe28be34524sdbdaa34d37d1f2294a",
  "account_settings_templates": [
    {
      "id": "AccountSettingsTemplate-2c434aba-38a4-402c-a8a1-c444570b7408",
      "version": 1,
      "account_id": "5bbe28be34524sdbdaa34d37d1f2294a",
      "name": "My new account settings template",
      "committed": true,
      "account_settings": {
        "restrict_create_platform_apikey": "RESTRICTED",
        "restrict_create_service_id": "NOT_RESTRICTED",
        "max_sessions_per_identity": "5",
        "mfa": "LEVEL3"
      },
      "created_at": "2023-01-12T13:09:59:761+0000",
      "created_by_id": "IBMid-12345678901",
      "last_modified_at": "2023-02-24T13:48:44:198+0000",
      "last_modified_by_id": "IBMid-12345678901",
      "entity_tag": "6-aa54ac91e59055f80b58da2c5a4c426f",
      "crn": "crn:v1:bluemix:public:iam-identity::a/5bbe28be34524sdbdaa34d37d1f2294a::template:AccountSettingsTemplate-2c434aba-38a4-402c-a8a1-c444570b7408"
    }
  ]
}
Copy to clipboard

Success example

{
  "offset": 0,
  "limit": 20,
  "first": "https://iam.cloud.ibm.com/v1/account_settings_templates?account_id=5bbe28be34524sdbdaa34d37d1f2294a",
  "account_settings_templates": [
    {
      "id": "AccountSettingsTemplate-2c434aba-38a4-402c-a8a1-c444570b7408",
      "version": 1,
      "account_id": "5bbe28be34524sdbdaa34d37d1f2294a",
      "name": "My new account settings template",
      "committed": true,
      "account_settings": {
        "restrict_create_platform_apikey": "RESTRICTED",
        "restrict_create_service_id": "NOT_RESTRICTED",
        "max_sessions_per_identity": "5",
        "mfa": "LEVEL3"
      },
      "created_at": "2023-01-12T13:09:59:761+0000",
      "created_by_id": "IBMid-12345678901",
      "last_modified_at": "2023-02-24T13:48:44:198+0000",
      "last_modified_by_id": "IBMid-12345678901",
      "entity_tag": "6-aa54ac91e59055f80b58da2c5a4c426f",
      "crn": "crn:v1:bluemix:public:iam-identity::a/5bbe28be34524sdbdaa34d37d1f2294a::template:AccountSettingsTemplate-2c434aba-38a4-402c-a8a1-c444570b7408"
    }
  ]
}
Copy to clipboard

Create a new account settings template in an enterprise account.

POST /v1/account_settings_templates

(iamIdentity *IamIdentityV1) CreateAccountSettingsTemplate(createAccountSettingsTemplateOptions *CreateAccountSettingsTemplateOptions) (result *AccountSettingsTemplateResponse, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) CreateAccountSettingsTemplateWithContext(ctx context.Context, createAccountSettingsTemplateOptions *CreateAccountSettingsTemplateOptions) (result *AccountSettingsTemplateResponse, response *core.DetailedResponse, err error)

ServiceCall<AccountSettingsTemplateResponse> createAccountSettingsTemplate(CreateAccountSettingsTemplateOptions createAccountSettingsTemplateOptions)
Copy to clipboard

createAccountSettingsTemplate(params)

create_account_settings_template(
        self,
        *,
        account_id: Optional[str] = None,
        name: Optional[str] = None,
        description: Optional[str] = None,
        account_settings: Optional['AccountSettingsComponent'] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.account-settings-template.create

Request

Instantiate the CreateAccountSettingsTemplateOptions struct and set the fields to provide parameter values for the CreateAccountSettingsTemplate method.

Use the CreateAccountSettingsTemplateOptions.Builder to create a CreateAccountSettingsTemplateOptions object that contains the parameter values for the createAccountSettingsTemplate method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Request Body

Required*

AccountSettingsTemplateRequest

Request to create an account settings template.

parameter

WithContext method only

CreateAccountSettingsTemplateOptions

The CreateAccountSettingsTemplate options.

CreateAccountSettingsTemplateOptions

The createAccountSettingsTemplate options.

parameters

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

parameters

account_id
str
ID of the account where the template resides.
name
str
The name of the trusted profile template. This is visible only in the enterprise account.
description
str
The description of the trusted profile template. Describe the template for enterprise account users.
account_settings

Example request

curl -X POST "https://iam.cloud.ibm.com/v1/account_settings_templates" --header "Content-Type: application/json" --header "Authorization: Bearer $TOKEN" --data '{
    "account_id": "5bbe28be34524sdbdaa34d37d1f2294a",
    "name": "my template",
    "account_settings": {
        "restrict_create_platform_apikey": "RESTRICTED",
        "restrict_create_service_id":  "NOT_RESTRICTED",
        "max_sessions_per_identity": "5",
        "mfa": "LEVEL3"
    }
}'
Copy to clipboard

Example request

settings := &iamidentityv1.AccountSettingsComponent{
  Mfa:                                  core.StringPtr("LEVEL1"),
  SystemAccessTokenExpirationInSeconds: core.StringPtr("3000"),
}

createOptions := &iamidentityv1.CreateAccountSettingsTemplateOptions{
  Name:            &accountSettingsTemplateName,
  Description:     core.StringPtr("GoSDK test Account Settings Template"),
  AccountID:       &enterpriseAccountID,
  AccountSettings: settings,
}

createResponse, response, err := iamIdentityService.CreateAccountSettingsTemplate(createOptions)

b, _ := json.MarshalIndent(createResponse, "", "  ")
fmt.Println(string(b))

// Grab the ID and Etag value from the response for use in the update operation.
accountSettingsTemplateId = *createResponse.ID
accountSettingsTemplateVersion = *createResponse.Version
accountSettingsTemplateEtag = response.GetHeaders().Get("Etag")
Copy to clipboard

Example request

AccountSettingsComponent accountSettings = new AccountSettingsComponent.Builder()
    .mfa("LEVEL1")
    .systemAccessTokenExpirationInSeconds("3000")
    .build();

CreateAccountSettingsTemplateOptions createOptions = new CreateAccountSettingsTemplateOptions.Builder()
    .accountId(enterpriseAccountId)
    .name(accountSettingsTemplateName)
    .description("IAM enterprise account settings template example")
    .accountSettings(accountSettings)
    .build();

Response<AccountSettingsTemplateResponse> createResponse = service.createAccountSettingsTemplate(createOptions).execute();
AccountSettingsTemplateResponse createResult = createResponse.getResult();

// Save the id for use by other test methods.
accountSettingsTemplateId = createResult.getId();
accountSettingsTemplateVersion = createResult.getVersion().longValue();

System.out.println(createResult);
Copy to clipboard

Example request

const settings = {
  mfa: "LEVEL1",
  system_access_token_expiration_in_seconds: "3000",
}
const templateParams = {
  name: "Example-Account-Settings-Template",
  description: "IAM enterprise account settings template example",
  accountId: enterpriseAccountId,
  accountSettings: settings,
}

try {
  const res = await iamIdentityService.createAccountSettingsTemplate(templateParams);
  accountSettingsTemplateEtag = res.headers.etag;
  const { result } = res;
  accountSettingsTemplateId = result.id;
  accountSettingsTemplateVersion = result.version;
  console.log(JSON.stringify(result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

account_settings = {}
account_settings['mfa'] = 'LEVEL1'
account_settings['system_access_token_expiration_in_seconds'] = 3000

create_response = iam_identity_service.create_account_settings_template(
  name='Example-Account-Settings-Template',
  description='IAM enterprise account settings template example',
  account_id=enterprise_account_id,
  account_settings=account_settings,
)
account_settings_template = create_response.get_result()
print('\ncreate_account_settings_template() response: ', json.dumps(account_settings_template, indent=2))
Copy to clipboard

Response

Response Body

AccountSettingsTemplateResponse

Response body format for account settings template REST requests

AccountSettingsTemplateResponse

Response body format for account settings template REST requests.

AccountSettingsTemplateResponse

Response body format for account settings template REST requests.

AccountSettingsTemplateResponse

Response body format for account settings template REST requests.

AccountSettingsTemplateResponse

Response body format for account settings template REST requests.

Status Code

201
Template successfully created
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

Example responses

Status 201

{
  "id": "AccountSettingsTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9",
  "version": 1,
  "account_id": "5bbe28be34524sdbdaa34d37d1f2294a",
  "name": "my template name",
  "committed": false,
  "account_settings": {
    "restrict_create_platform_apikey": "RESTRICTED",
    "restrict_create_service_id": "NOT_RESTRICTED",
    "max_sessions_per_identity": "5",
    "mfa": "LEVEL3"
  },
  "created_at": "2023-03-07T13:55:33:428+0000",
  "created_by_id": "IBMid-12345678901",
  "last_modified_at": "2023-03-07T13:55:33:428+0000",
  "last_modified_by_id": "IBMid-12345678901",
  "entity_tag": "1-2da85a8f1172fc3527378318d3182778",
  "crn": "crn:v1:bluemix:public:iam-identity::a/5bbe28be34524sdbdaa34d37d1f2294a::template:AccountSettingsTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9"
}
Copy to clipboard

Success example

{
  "id": "AccountSettingsTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9",
  "version": 1,
  "account_id": "5bbe28be34524sdbdaa34d37d1f2294a",
  "name": "my template name",
  "committed": false,
  "account_settings": {
    "restrict_create_platform_apikey": "RESTRICTED",
    "restrict_create_service_id": "NOT_RESTRICTED",
    "max_sessions_per_identity": "5",
    "mfa": "LEVEL3"
  },
  "created_at": "2023-03-07T13:55:33:428+0000",
  "created_by_id": "IBMid-12345678901",
  "last_modified_at": "2023-03-07T13:55:33:428+0000",
  "last_modified_by_id": "IBMid-12345678901",
  "entity_tag": "1-2da85a8f1172fc3527378318d3182778",
  "crn": "crn:v1:bluemix:public:iam-identity::a/5bbe28be34524sdbdaa34d37d1f2294a::template:AccountSettingsTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9"
}
Copy to clipboard

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

GET /v1/account_settings_templates/{template_id}

(iamIdentity *IamIdentityV1) GetLatestAccountSettingsTemplateVersion(getLatestAccountSettingsTemplateVersionOptions *GetLatestAccountSettingsTemplateVersionOptions) (result *AccountSettingsTemplateResponse, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) GetLatestAccountSettingsTemplateVersionWithContext(ctx context.Context, getLatestAccountSettingsTemplateVersionOptions *GetLatestAccountSettingsTemplateVersionOptions) (result *AccountSettingsTemplateResponse, response *core.DetailedResponse, err error)

ServiceCall<AccountSettingsTemplateResponse> getLatestAccountSettingsTemplateVersion(GetLatestAccountSettingsTemplateVersionOptions getLatestAccountSettingsTemplateVersionOptions)
Copy to clipboard

getLatestAccountSettingsTemplateVersion(params)

get_latest_account_settings_template_version(
        self,
        template_id: str,
        *,
        include_history: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.account-settings-template.read

Request

Instantiate the GetLatestAccountSettingsTemplateVersionOptions struct and set the fields to provide parameter values for the GetLatestAccountSettingsTemplateVersion method.

Use the GetLatestAccountSettingsTemplateVersionOptions.Builder to create a GetLatestAccountSettingsTemplateVersionOptions object that contains the parameter values for the getLatestAccountSettingsTemplateVersion method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the 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

Default: false

parameter

WithContext method only

GetLatestAccountSettingsTemplateVersionOptions

The GetLatestAccountSettingsTemplateVersion options.

GetLatestAccountSettingsTemplateVersionOptions

The getLatestAccountSettingsTemplateVersion options.

parameters

templateId
Required*
string
ID of the account settings template.
includeHistory
boolean
Defines if the entity history is included in the response.

Default: false

parameters

template_id
Required*
str
ID of the account settings template.
include_history
bool
Defines if the entity history is included in the response.

Default: false

Example request

curl -X GET "https://iam.cloud.ibm.com/v1/account_settings_templates/AccountSettingsTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9" --header "Content-Type: application/json" --header "Authorization: Bearer $TOKEN" 
Copy to clipboard

Example request

getOptions := &iamidentityv1.GetLatestAccountSettingsTemplateVersionOptions{
  TemplateID: &accountSettingsTemplateId,
}

getResponse, response, err := iamIdentityService.GetLatestAccountSettingsTemplateVersion(getOptions)

b, _ := json.MarshalIndent(getResponse, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

GetLatestAccountSettingsTemplateVersionOptions getOptions = new GetLatestAccountSettingsTemplateVersionOptions.Builder()
    .templateId(accountSettingsTemplateId)
    .build();

Response<AccountSettingsTemplateResponse> getResponse = service.getLatestAccountSettingsTemplateVersion(getOptions).execute();
AccountSettingsTemplateResponse getResult = getResponse.getResult();

System.out.println(getResult);

Example request

const params = {
  templateId: accountSettingsTemplateId,
}
try {
  const res = await iamIdentityService.getLatestAccountSettingsTemplateVersion(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

get_response = iam_identity_service.get_latest_account_settings_template_version(
  template_id=account_settings_template_id
)
account_settings_template = get_response.get_result()
print(
  '\nget_latest_account_settings_template_version response: ',
  json.dumps(account_settings_template, indent=2),
)
Copy to clipboard

Response

Response Body

AccountSettingsTemplateResponse

Response body format for account settings template REST requests

AccountSettingsTemplateResponse

Response body format for account settings template REST requests.

AccountSettingsTemplateResponse

Response body format for account settings template REST requests.

AccountSettingsTemplateResponse

Response body format for account settings template REST requests.

AccountSettingsTemplateResponse

Response body format for account settings template REST requests.

Status Code

200
Successful Template retrieval
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

Example responses

Status 200

{
  "id": "AccountSettingsTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9",
  "version": 1,
  "account_id": "5bbe28be34524sdbdaa34d37d1f2294a",
  "name": "my template name",
  "committed": false,
  "account_settings": {
    "restrict_create_platform_apikey": "RESTRICTED",
    "restrict_create_service_id": "NOT_RESTRICTED",
    "max_sessions_per_identity": "5",
    "mfa": "LEVEL3"
  },
  "created_at": "2023-03-07T13:55:33:428+0000",
  "created_by_id": "IBMid-12345678901",
  "last_modified_at": "2023-03-07T13:55:33:428+0000",
  "last_modified_by_id": "IBMid-12345678901",
  "entity_tag": "1-2da85a8f1172fc3527378318d3182778",
  "crn": "crn:v1:bluemix:public:iam-identity::a/5bbe28be34524sdbdaa34d37d1f2294a::template:AccountSettingsTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9"
}
Copy to clipboard

Success example

{
  "id": "AccountSettingsTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9",
  "version": 1,
  "account_id": "5bbe28be34524sdbdaa34d37d1f2294a",
  "name": "my template name",
  "committed": false,
  "account_settings": {
    "restrict_create_platform_apikey": "RESTRICTED",
    "restrict_create_service_id": "NOT_RESTRICTED",
    "max_sessions_per_identity": "5",
    "mfa": "LEVEL3"
  },
  "created_at": "2023-03-07T13:55:33:428+0000",
  "created_by_id": "IBMid-12345678901",
  "last_modified_at": "2023-03-07T13:55:33:428+0000",
  "last_modified_by_id": "IBMid-12345678901",
  "entity_tag": "1-2da85a8f1172fc3527378318d3182778",
  "crn": "crn:v1:bluemix:public:iam-identity::a/5bbe28be34524sdbdaa34d37d1f2294a::template:AccountSettingsTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9"
}
Copy to clipboard

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.

DELETE /v1/account_settings_templates/{template_id}

(iamIdentity *IamIdentityV1) DeleteAllVersionsOfAccountSettingsTemplate(deleteAllVersionsOfAccountSettingsTemplateOptions *DeleteAllVersionsOfAccountSettingsTemplateOptions) (response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) DeleteAllVersionsOfAccountSettingsTemplateWithContext(ctx context.Context, deleteAllVersionsOfAccountSettingsTemplateOptions *DeleteAllVersionsOfAccountSettingsTemplateOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> deleteAllVersionsOfAccountSettingsTemplate(DeleteAllVersionsOfAccountSettingsTemplateOptions deleteAllVersionsOfAccountSettingsTemplateOptions)
Copy to clipboard

deleteAllVersionsOfAccountSettingsTemplate(params)

delete_all_versions_of_account_settings_template(
        self,
        template_id: str,
        **kwargs,
    ) -> DetailedResponse

Authorization

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

iam-identity.account-settings-template.delete

Request

Instantiate the DeleteAllVersionsOfAccountSettingsTemplateOptions struct and set the fields to provide parameter values for the DeleteAllVersionsOfAccountSettingsTemplate method.

Use the DeleteAllVersionsOfAccountSettingsTemplateOptions.Builder to create a DeleteAllVersionsOfAccountSettingsTemplateOptions object that contains the parameter values for the deleteAllVersionsOfAccountSettingsTemplate method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

template_id
Required*
string
ID of the account settings template

parameter

WithContext method only

DeleteAllVersionsOfAccountSettingsTemplateOptions

The DeleteAllVersionsOfAccountSettingsTemplate options.

DeleteAllVersionsOfAccountSettingsTemplateOptions

The deleteAllVersionsOfAccountSettingsTemplate options.

parameters

templateId
Required*
string
ID of the account settings template.

parameters

template_id
Required*
str
ID of the account settings template.

Example request

curl -X DELETE "https://iam.cloud.ibm.com/v1/account_settings_templates/AccountSettingsTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9" --header "Content-Type: application/json" --header "Authorization: Bearer $TOKEN" 
Copy to clipboard

Example request

deleteOptions := &iamidentityv1.DeleteAllVersionsOfAccountSettingsTemplateOptions{
  TemplateID: &accountSettingsTemplateId,
}

response, err := iamIdentityService.DeleteAllVersionsOfAccountSettingsTemplate(deleteOptions)

Example request

DeleteAllVersionsOfAccountSettingsTemplateOptions deleteTeplateOptions = new DeleteAllVersionsOfAccountSettingsTemplateOptions.Builder()
    .templateId(accountSettingsTemplateId)
    .build();

Response<Void> deleteResponse = service.deleteAllVersionsOfAccountSettingsTemplate(deleteTeplateOptions).execute();

Example request

const params = {
  templateId: accountSettingsTemplateId,
}
try {
  const res = await iamIdentityService.deleteAllVersionsOfAccountSettingsTemplate(params);
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

delete_response = iam_identity_service.delete_all_versions_of_account_settings_template(
  template_id=account_settings_template_id
)

Response

Status Code

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

No Sample Response

This method does not specify any sample responses.

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

GET /v1/account_settings_templates/{template_id}/versions

(iamIdentity *IamIdentityV1) ListVersionsOfAccountSettingsTemplate(listVersionsOfAccountSettingsTemplateOptions *ListVersionsOfAccountSettingsTemplateOptions) (result *AccountSettingsTemplateList, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) ListVersionsOfAccountSettingsTemplateWithContext(ctx context.Context, listVersionsOfAccountSettingsTemplateOptions *ListVersionsOfAccountSettingsTemplateOptions) (result *AccountSettingsTemplateList, response *core.DetailedResponse, err error)

ServiceCall<AccountSettingsTemplateList> listVersionsOfAccountSettingsTemplate(ListVersionsOfAccountSettingsTemplateOptions listVersionsOfAccountSettingsTemplateOptions)
Copy to clipboard

listVersionsOfAccountSettingsTemplate(params)

list_versions_of_account_settings_template(
        self,
        template_id: str,
        *,
        limit: Optional[str] = None,
        pagetoken: Optional[str] = None,
        sort: Optional[str] = None,
        order: Optional[str] = None,
        include_history: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.account-settings-template.read

Request

Instantiate the ListVersionsOfAccountSettingsTemplateOptions struct and set the fields to provide parameter values for the ListVersionsOfAccountSettingsTemplate method.

Use the ListVersionsOfAccountSettingsTemplateOptions.Builder to create a ListVersionsOfAccountSettingsTemplateOptions object that contains the parameter values for the listVersionsOfAccountSettingsTemplate method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

template_id
Required*
string
ID of the account settings template

Query Parameters

limit
string
Optional size of a single page.

Possible values: 1 ≤ value ≤ 100
Default: 20
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

Allowable values: [created_at,last_modified_at,name]
Default: created_at
order
string
Optional sort order.

Allowable values: [asc,desc]
Default: asc
include_history
string
Defines if the entity history is included in the response

Default: false

parameter

WithContext method only

ListVersionsOfAccountSettingsTemplateOptions

The ListVersionsOfAccountSettingsTemplate options.

ListVersionsOfAccountSettingsTemplateOptions

The listVersionsOfAccountSettingsTemplate options.

parameters

templateId
Required*
string
ID of the account settings template.
limit
string
Optional size of a single page.

Possible values: 1 ≤ value ≤ 100
Default: 20
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.

Allowable values: [created_at,last_modified_at,name]
Default: created_at
order
string
Optional sort order.

Allowable values: [asc,desc]
Default: asc
includeHistory
string
Defines if the entity history is included in the response.

Default: false

parameters

template_id
Required*
str
ID of the account settings template.
limit
str
Optional size of a single page.

Possible values: 1 ≤ value ≤ 100
Default: 20
pagetoken
str
Optional Prev or Next page token returned from a previous query execution. Default is start with first page.
sort
str
Optional sort property. If specified, the returned templated are sorted according to this property.

Allowable values: [created_at,last_modified_at,name]
Default: created_at
order
str
Optional sort order.

Allowable values: [asc,desc]
Default: asc
include_history
str
Defines if the entity history is included in the response.

Default: false

Example request

curl -X GET "https://iam.cloud.ibm.com/v1/account_settings_templates/AccountSettingsTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9/versions/" --header "Content-Type: application/json" --header "Authorization: Bearer $TOKEN" 
Copy to clipboard

Example request

listOptions := &iamidentityv1.ListVersionsOfAccountSettingsTemplateOptions{
  TemplateID: &accountSettingsTemplateId,
}

listResponse, response, err := iamIdentityService.ListVersionsOfAccountSettingsTemplate(listOptions)

b, _ := json.MarshalIndent(listResponse, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

ListVersionsOfAccountSettingsTemplateOptions listOptions = new ListVersionsOfAccountSettingsTemplateOptions.Builder()
    .templateId(accountSettingsTemplateId)
    .build();

Response<AccountSettingsTemplateList> listResponse = service.listVersionsOfAccountSettingsTemplate(listOptions).execute();
AccountSettingsTemplateList listResult = listResponse.getResult();

System.out.println(listResult);

Example request

const params = {
  templateId: accountSettingsTemplateId,
}
try {
  const res = await iamIdentityService.listVersionsOfAccountSettingsTemplate(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

list_response = iam_identity_service.list_versions_of_account_settings_template(
  template_id=account_settings_template_id
)
account_settings_template_list = list_response.get_result()
print(
  '\nlist_account_settings_template_versions response: ',
  json.dumps(account_settings_template_list, indent=2),
)
Copy to clipboard

Response

Response Body

AccountSettingsTemplateList

Status Code

200
Successful Template retrieval
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

Example responses

Status 200

{
  "offset": 0,
  "limit": 20,
  "first": "https://iam.cloud.ibm.com/v1/account_settings_templates?account_id=5bbe28be34524sdbdaa34d37d1f2294a",
  "account_settings_templates": [
    {
      "id": "AccountSettingsTemplate-2c434aba-38a4-402c-a8a1-c444570b7408",
      "version": 1,
      "account_id": "5bbe28be34524sdbdaa34d37d1f2294a",
      "name": "My new account settings template",
      "committed": true,
      "account_settings": {
        "restrict_create_platform_apikey": "RESTRICTED",
        "restrict_create_service_id": "NOT_RESTRICTED",
        "max_sessions_per_identity": "5",
        "mfa": "LEVEL3"
      },
      "created_at": "2023-01-12T13:09:59:761+0000",
      "created_by_id": "IBMid-12345678901",
      "last_modified_at": "2023-02-24T13:48:44:198+0000",
      "last_modified_by_id": "IBMid-12345678901",
      "entity_tag": "6-aa54ac91e59055f80b58da2c5a4c426f",
      "crn": "crn:v1:bluemix:public:iam-identity::a/5bbe28be34524sdbdaa34d37d1f2294a::template:AccountSettingsTemplate-2c434aba-38a4-402c-a8a1-c444570b7408"
    }
  ]
}
Copy to clipboard

Success example

{
  "offset": 0,
  "limit": 20,
  "first": "https://iam.cloud.ibm.com/v1/account_settings_templates?account_id=5bbe28be34524sdbdaa34d37d1f2294a",
  "account_settings_templates": [
    {
      "id": "AccountSettingsTemplate-2c434aba-38a4-402c-a8a1-c444570b7408",
      "version": 1,
      "account_id": "5bbe28be34524sdbdaa34d37d1f2294a",
      "name": "My new account settings template",
      "committed": true,
      "account_settings": {
        "restrict_create_platform_apikey": "RESTRICTED",
        "restrict_create_service_id": "NOT_RESTRICTED",
        "max_sessions_per_identity": "5",
        "mfa": "LEVEL3"
      },
      "created_at": "2023-01-12T13:09:59:761+0000",
      "created_by_id": "IBMid-12345678901",
      "last_modified_at": "2023-02-24T13:48:44:198+0000",
      "last_modified_by_id": "IBMid-12345678901",
      "entity_tag": "6-aa54ac91e59055f80b58da2c5a4c426f",
      "crn": "crn:v1:bluemix:public:iam-identity::a/5bbe28be34524sdbdaa34d37d1f2294a::template:AccountSettingsTemplate-2c434aba-38a4-402c-a8a1-c444570b7408"
    }
  ]
}
Copy to clipboard

Create a new version of an account settings template in an Enterprise Account

Create a new version of an account settings template in an Enterprise Account.

POST /v1/account_settings_templates/{template_id}/versions

(iamIdentity *IamIdentityV1) CreateAccountSettingsTemplateVersion(createAccountSettingsTemplateVersionOptions *CreateAccountSettingsTemplateVersionOptions) (result *AccountSettingsTemplateResponse, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) CreateAccountSettingsTemplateVersionWithContext(ctx context.Context, createAccountSettingsTemplateVersionOptions *CreateAccountSettingsTemplateVersionOptions) (result *AccountSettingsTemplateResponse, response *core.DetailedResponse, err error)

ServiceCall<AccountSettingsTemplateResponse> createAccountSettingsTemplateVersion(CreateAccountSettingsTemplateVersionOptions createAccountSettingsTemplateVersionOptions)
Copy to clipboard

createAccountSettingsTemplateVersion(params)

create_account_settings_template_version(
        self,
        template_id: str,
        *,
        account_id: Optional[str] = None,
        name: Optional[str] = None,
        description: Optional[str] = None,
        account_settings: Optional['AccountSettingsComponent'] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.account-settings-template.create

Request

Instantiate the CreateAccountSettingsTemplateVersionOptions struct and set the fields to provide parameter values for the CreateAccountSettingsTemplateVersion method.

Use the CreateAccountSettingsTemplateVersionOptions.Builder to create a CreateAccountSettingsTemplateVersionOptions object that contains the parameter values for the createAccountSettingsTemplateVersion method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

template_id
Required*
string
ID of the account settings template

Request Body

Required*

AccountSettingsTemplateRequest

Request to create new version of an account settings template

parameter

WithContext method only

CreateAccountSettingsTemplateVersionOptions

The CreateAccountSettingsTemplateVersion options.

CreateAccountSettingsTemplateVersionOptions

The createAccountSettingsTemplateVersion options.

parameters

templateId
Required*
string
ID of the account settings template.
accountId
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.
accountSettings

parameters

template_id
Required*
str
ID of the account settings template.
account_id
str
ID of the account where the template resides.
name
str
The name of the trusted profile template. This is visible only in the enterprise account.
description
str
The description of the trusted profile template. Describe the template for enterprise account users.
account_settings

Example request

curl -X POST "https://iam.cloud.ibm.com/v1/account_settings_templates/{template_id}/versions" --header "Content-Type: application/json" --header "Authorization: Bearer $TOKEN" --data '{
    "account_id": "5bbe28be34524sdbdaa34d37d1f2294a",
    "name": "my template name",
    "account_settings": {
        "restrict_create_platform_apikey": "RESTRICTED",
        "restrict_create_service_id": "NOT_RESTRICTED",
        "max_sessions_per_identity": 5,
        "mfa": "LEVEL3"
    }
}'
Copy to clipboard

Example request

settings := &iamidentityv1.AccountSettingsComponent{
  Mfa:                                  core.StringPtr("LEVEL1"),
  SystemAccessTokenExpirationInSeconds: core.StringPtr("2600"),
  RestrictCreatePlatformApikey:         core.StringPtr("RESTRICTED"),
  RestrictCreateServiceID:              core.StringPtr("RESTRICTED"),
}

createOptions := &iamidentityv1.CreateAccountSettingsTemplateVersionOptions{
  Name:            &accountSettingsTemplateName,
  Description:     core.StringPtr("GoSDK test Account Settings Template - new version"),
  AccountID:       &enterpriseAccountID,
  TemplateID:      &accountSettingsTemplateId,
  AccountSettings: settings,
}

createResponse, response, err := iamIdentityService.CreateAccountSettingsTemplateVersion(createOptions)

b, _ := json.MarshalIndent(createResponse, "", "  ")
fmt.Println(string(b))

// save the new version to be used in subsequent calls
accountSettingsTemplateVersion = *createResponse.Version
Copy to clipboard

Example request

AccountSettingsComponent accountSettings = new AccountSettingsComponent.Builder()
    .mfa("LEVEL1")
    .systemAccessTokenExpirationInSeconds("2600")
    .restrictCreatePlatformApikey("RESTRICTED")
    .restrictCreateServiceId("RESTRICTED")
    .build();
CreateAccountSettingsTemplateVersionOptions createOptions = new CreateAccountSettingsTemplateVersionOptions.Builder()
    .accountId(enterpriseAccountId)
    .templateId(accountSettingsTemplateId)
    .name(accountSettingsTemplateName)
    .description("IAM enterprise account settings template example - new version")
    .accountSettings(accountSettings)
    .build();

Response<AccountSettingsTemplateResponse> createResponse = service.createAccountSettingsTemplateVersion(createOptions).execute();
AccountSettingsTemplateResponse createResult = createResponse.getResult();

// Save the version for use by other test methods.
accountSettingsTemplateVersion = createResult.getVersion().longValue();

System.out.println(createResult);
Copy to clipboard

Example request

    const settings = {
      mfa: "LEVEL1",
      system_access_token_expiration_in_seconds: "2600",
      restrict_create_platform_apikey: "RESTRICTED",
      restrict_create_service_id: "RESTRICTED",
    }
    const templateParams = {
      templateId: accountSettingsTemplateId,
      name: "Example-Account-Settings-Template",
      description: "IAM enterprise account settings template example - new version",
      accountId: enterpriseAccountId,
      accountSettings: settings,
    }
    try {
      const res = await iamIdentityService.createAccountSettingsTemplateVersion(templateParams);
      const { result } = res;
      accountSettingsTemplateVersion = result.version;
      console.log(JSON.stringify(result, null, 2));
    } catch (err) {
      console.warn(err);
    }
Copy to clipboard

Example request

account_settings = {}
account_settings['mfa'] = 'LEVEL1'
account_settings['system_access_token_expiration_in_seconds'] = 2600
account_settings['restrict_create_platform_apikey'] = 'RESTRICTED'
account_settings['restrict_create_service_id'] = 'RESTRICTED'

create_response = iam_identity_service.create_account_settings_template_version(
  template_id=account_settings_template_id,
  name='Example-Account-Settings-Template',
  description='IAM enterprise account settings template example - new version',
  account_id=enterprise_account_id,
  account_settings=account_settings,
)
account_settings_template = create_response.get_result()
print(
  '\ncreate_account_settings_template_version() response: ',
  json.dumps(account_settings_template, indent=2),
)
Copy to clipboard

Response

Response Body

AccountSettingsTemplateResponse

Response body format for account settings template REST requests

AccountSettingsTemplateResponse

Response body format for account settings template REST requests.

AccountSettingsTemplateResponse

Response body format for account settings template REST requests.

AccountSettingsTemplateResponse

Response body format for account settings template REST requests.

AccountSettingsTemplateResponse

Response body format for account settings template REST requests.

Status Code

201
Template version created successfully
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

Example responses

Status 201

{
  "id": "AccountSettingsTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9",
  "version": 2,
  "account_id": "5bbe28be34524sdbdaa34d37d1f2294a",
  "name": "my template name",
  "committed": false,
  "account_settings": {
    "restrict_create_platform_apikey": "RESTRICTED",
    "restrict_create_service_id": "NOT_RESTRICTED",
    "max_sessions_per_identity": "5",
    "mfa": "LEVEL3"
  },
  "created_at": "2023-03-07T13:55:33:428+0000",
  "created_by_id": "IBMid-12345678901",
  "last_modified_at": "2023-03-07T13:55:33:428+0000",
  "last_modified_by_id": "IBMid-12345678901",
  "entity_tag": "1-2da85a8f1172fc3527378318d3182778",
  "crn": "crn:v1:bluemix:public:iam-identity::a/5bbe28be34524sdbdaa34d37d1f2294a::template:AccountSettingsTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9"
}
Copy to clipboard

Success example

{
  "id": "AccountSettingsTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9",
  "version": 2,
  "account_id": "5bbe28be34524sdbdaa34d37d1f2294a",
  "name": "my template name",
  "committed": false,
  "account_settings": {
    "restrict_create_platform_apikey": "RESTRICTED",
    "restrict_create_service_id": "NOT_RESTRICTED",
    "max_sessions_per_identity": "5",
    "mfa": "LEVEL3"
  },
  "created_at": "2023-03-07T13:55:33:428+0000",
  "created_by_id": "IBMid-12345678901",
  "last_modified_at": "2023-03-07T13:55:33:428+0000",
  "last_modified_by_id": "IBMid-12345678901",
  "entity_tag": "1-2da85a8f1172fc3527378318d3182778",
  "crn": "crn:v1:bluemix:public:iam-identity::a/5bbe28be34524sdbdaa34d37d1f2294a::template:AccountSettingsTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9"
}
Copy to clipboard

Get a specific version of an account settings template in an Enterprise Account

Get a specific version of an account settings template in an Enterprise Account.

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

(iamIdentity *IamIdentityV1) GetAccountSettingsTemplateVersion(getAccountSettingsTemplateVersionOptions *GetAccountSettingsTemplateVersionOptions) (result *AccountSettingsTemplateResponse, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) GetAccountSettingsTemplateVersionWithContext(ctx context.Context, getAccountSettingsTemplateVersionOptions *GetAccountSettingsTemplateVersionOptions) (result *AccountSettingsTemplateResponse, response *core.DetailedResponse, err error)

ServiceCall<AccountSettingsTemplateResponse> getAccountSettingsTemplateVersion(GetAccountSettingsTemplateVersionOptions getAccountSettingsTemplateVersionOptions)
Copy to clipboard

getAccountSettingsTemplateVersion(params)

get_account_settings_template_version(
        self,
        template_id: str,
        version: str,
        *,
        include_history: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.account-settings-template.read

Request

Instantiate the GetAccountSettingsTemplateVersionOptions struct and set the fields to provide parameter values for the GetAccountSettingsTemplateVersion method.

Use the GetAccountSettingsTemplateVersionOptions.Builder to create a GetAccountSettingsTemplateVersionOptions object that contains the parameter values for the getAccountSettingsTemplateVersion method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the 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

Default: false

parameter

WithContext method only

GetAccountSettingsTemplateVersionOptions

The GetAccountSettingsTemplateVersion options.

GetAccountSettingsTemplateVersionOptions

The getAccountSettingsTemplateVersion options.

parameters

templateId
Required*
string
ID of the account settings template.
version
Required*
string
Version of the account settings template.
includeHistory
boolean
Defines if the entity history is included in the response.

Default: false

parameters

template_id
Required*
str
ID of the account settings template.
version
Required*
str
Version of the account settings template.
include_history
bool
Defines if the entity history is included in the response.

Default: false

Example request

curl -X GET "https://iam.cloud.ibm.com/v1/account_settings_templates/AccountSettingsTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9/versions/1" --header "Content-Type: application/json" --header "Authorization: Bearer $TOKEN" 
Copy to clipboard

Example request

getOptions := &iamidentityv1.GetAccountSettingsTemplateVersionOptions{
  TemplateID: &accountSettingsTemplateId,
  Version:    core.StringPtr(strconv.FormatInt(accountSettingsTemplateVersion, 10)),
}

getResponse, response, err := iamIdentityService.GetAccountSettingsTemplateVersion(getOptions)

b, _ := json.MarshalIndent(getResponse, "", "  ")
fmt.Println(string(b))

// Grab the Etag value from the response for use in the update operation.
accountSettingsTemplateEtag = response.GetHeaders().Get("Etag")
Copy to clipboard

Example request

GetAccountSettingsTemplateVersionOptions getOptions = new GetAccountSettingsTemplateVersionOptions.Builder()
    .templateId(accountSettingsTemplateId)
    .version(Long.toString(accountSettingsTemplateVersion))
    .build();

Response<AccountSettingsTemplateResponse> response = service.getAccountSettingsTemplateVersion(getOptions).execute();
AccountSettingsTemplateResponse getResult = response.getResult();

// Grab the Etag value from the response for use in the update operation.
accountSettingsTemplateEtag = response.getHeaders().values("Etag").get(0);

System.out.println(getResult);
Copy to clipboard

Example request

const params = {
  templateId: accountSettingsTemplateId,
  version: accountSettingsTemplateVersion,
}
try {
  const res = await iamIdentityService.getAccountSettingsTemplateVersion(params);
  accountSettingsTemplateEtag = res.headers.etag;
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

get_response = iam_identity_service.get_account_settings_template_version(
  template_id=account_settings_template_id, version=str(account_settings_template_version)
)

account_settings_template = get_response.get_result()
print('\nget_account_settings_template response: ', json.dumps(account_settings_template, indent=2))
Copy to clipboard

Response

Response Body

AccountSettingsTemplateResponse

Response body format for account settings template REST requests

AccountSettingsTemplateResponse

Response body format for account settings template REST requests.

AccountSettingsTemplateResponse

Response body format for account settings template REST requests.

AccountSettingsTemplateResponse

Response body format for account settings template REST requests.

AccountSettingsTemplateResponse

Response body format for account settings template REST requests.

Status Code

200
Successful Template retrieval
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

Example responses

Status 200

{
  "id": "AccountSettingsTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9",
  "version": 1,
  "account_id": "5bbe28be34524sdbdaa34d37d1f2294a",
  "name": "my template name",
  "committed": false,
  "account_settings": {
    "restrict_create_platform_apikey": "RESTRICTED",
    "restrict_create_service_id": "NOT_RESTRICTED",
    "max_sessions_per_identity": "5",
    "mfa": "LEVEL3"
  },
  "created_at": "2023-03-07T13:55:33:428+0000",
  "created_by_id": "IBMid-12345678901",
  "last_modified_at": "2023-03-07T13:55:33:428+0000",
  "last_modified_by_id": "IBMid-12345678901",
  "entity_tag": "1-2da85a8f1172fc3527378318d3182778",
  "crn": "crn:v1:bluemix:public:iam-identity::a/5bbe28be34524sdbdaa34d37d1f2294a::template:AccountSettingsTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9"
}
Copy to clipboard

Success example

{
  "id": "AccountSettingsTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9",
  "version": 1,
  "account_id": "5bbe28be34524sdbdaa34d37d1f2294a",
  "name": "my template name",
  "committed": false,
  "account_settings": {
    "restrict_create_platform_apikey": "RESTRICTED",
    "restrict_create_service_id": "NOT_RESTRICTED",
    "max_sessions_per_identity": "5",
    "mfa": "LEVEL3"
  },
  "created_at": "2023-03-07T13:55:33:428+0000",
  "created_by_id": "IBMid-12345678901",
  "last_modified_at": "2023-03-07T13:55:33:428+0000",
  "last_modified_by_id": "IBMid-12345678901",
  "entity_tag": "1-2da85a8f1172fc3527378318d3182778",
  "crn": "crn:v1:bluemix:public:iam-identity::a/5bbe28be34524sdbdaa34d37d1f2294a::template:AccountSettingsTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9"
}
Copy to clipboard

Update a specific version of an account settings template in an Enterprise Account

Update a specific version of an account settings template in an Enterprise Account.

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

(iamIdentity *IamIdentityV1) UpdateAccountSettingsTemplateVersion(updateAccountSettingsTemplateVersionOptions *UpdateAccountSettingsTemplateVersionOptions) (result *AccountSettingsTemplateResponse, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) UpdateAccountSettingsTemplateVersionWithContext(ctx context.Context, updateAccountSettingsTemplateVersionOptions *UpdateAccountSettingsTemplateVersionOptions) (result *AccountSettingsTemplateResponse, response *core.DetailedResponse, err error)

ServiceCall<AccountSettingsTemplateResponse> updateAccountSettingsTemplateVersion(UpdateAccountSettingsTemplateVersionOptions updateAccountSettingsTemplateVersionOptions)
Copy to clipboard

updateAccountSettingsTemplateVersion(params)

update_account_settings_template_version(
        self,
        if_match: str,
        template_id: str,
        version: str,
        *,
        account_id: Optional[str] = None,
        name: Optional[str] = None,
        description: Optional[str] = None,
        account_settings: Optional['AccountSettingsComponent'] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.account-settings-template.update

Request

Instantiate the UpdateAccountSettingsTemplateVersionOptions struct and set the fields to provide parameter values for the UpdateAccountSettingsTemplateVersion method.

Use the UpdateAccountSettingsTemplateVersionOptions.Builder to create a UpdateAccountSettingsTemplateVersionOptions object that contains the parameter values for the updateAccountSettingsTemplateVersion method.

Custom Headers

If-Match
Required*
string
Entity tag of the Template to be updated. Specify the tag that you retrieved when reading the account settings template. This value helps identifying parallel usage of this API. Pass * to indicate to update any version available. This might result in stale updates.
Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

template_id
Required*
string
ID of the account settings template
version
Required*
string
Version of the account settings template

Request Body

Required*

AccountSettingsTemplateRequest

Request to create an account settings template.

parameter

WithContext method only

UpdateAccountSettingsTemplateVersionOptions

The UpdateAccountSettingsTemplateVersion options.

UpdateAccountSettingsTemplateVersionOptions

The updateAccountSettingsTemplateVersion options.

parameters

ifMatch
Required*
string
Entity tag of the Template to be updated. Specify the tag that you retrieved when reading the account settings template. This value helps identifying parallel usage of this API. Pass * to indicate to update any version available. This might result in stale updates.
templateId
Required*
string
ID of the account settings template.
version
Required*
string
Version of the account settings template.
accountId
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.
accountSettings

parameters

if_match
Required*
str
Entity tag of the Template to be updated. Specify the tag that you retrieved when reading the account settings template. This value helps identifying parallel usage of this API. Pass * to indicate to update any version available. This might result in stale updates.
template_id
Required*
str
ID of the account settings template.
version
Required*
str
Version of the account settings template.
account_id
str
ID of the account where the template resides.
name
str
The name of the trusted profile template. This is visible only in the enterprise account.
description
str
The description of the trusted profile template. Describe the template for enterprise account users.
account_settings

Example request

curl -X POST "https://iam.cloud.ibm.com/v1/account_settings_templates/{template_id}/versions" --header "Content-Type: application/json" --header "Authorization: Bearer $TOKEN" --data '{
    "account_id": "5bbe28be34524sdbdaa34d37d1f2294a",
    "name": "my template name",
    "account_settings": {
        "mfa": "NONE"
    }
}'
Copy to clipboard

Example request

settings := &iamidentityv1.AccountSettingsComponent{
  Mfa:                                  core.StringPtr("LEVEL1"),
  SystemAccessTokenExpirationInSeconds: core.StringPtr("3000"),
}

updateOptions := &iamidentityv1.UpdateAccountSettingsTemplateVersionOptions{
  AccountID:       &enterpriseAccountID,
  TemplateID:      &accountSettingsTemplateId,
  Version:         core.StringPtr(strconv.FormatInt(accountSettingsTemplateVersion, 10)),
  IfMatch:         &accountSettingsTemplateEtag,
  Name:            &accountSettingsTemplateName,
  Description:     core.StringPtr("GoSDK test Account Settings Template - updated"),
  AccountSettings: settings,
}

updateResponse, response, err := iamIdentityService.UpdateAccountSettingsTemplateVersion(updateOptions)

b, _ := json.MarshalIndent(updateResponse, "", "  ")
fmt.Println(string(b))

// Grab the Etag value from the response for use in the update operation.
accountSettingsTemplateEtag = response.GetHeaders().Get("Etag")
Copy to clipboard

Example request

AccountSettingsComponent accountSettings = new AccountSettingsComponent.Builder()
    .mfa("LEVEL1")
    .systemAccessTokenExpirationInSeconds("3000")
    .build();
UpdateAccountSettingsTemplateVersionOptions updateOptions = new UpdateAccountSettingsTemplateVersionOptions.Builder()
    .accountId(enterpriseAccountId)
    .templateId(accountSettingsTemplateId)
    .version(Long.toString(accountSettingsTemplateVersion))
    .ifMatch(accountSettingsTemplateEtag)
    .name(accountSettingsTemplateName)
    .description("IAM enterprise account settings template example - updated")
    .accountSettings(accountSettings)
    .build();

Response<AccountSettingsTemplateResponse> updateResponse = service.updateAccountSettingsTemplateVersion(updateOptions).execute();
AccountSettingsTemplateResponse updateResult = updateResponse.getResult();

// Grab the Etag value from the response for use in the update operation.
accountSettingsTemplateEtag = updateResponse.getHeaders().values("Etag").get(0);

System.out.println(updateResult);
Copy to clipboard

Example request

const settings = {
  mfa: "LEVEL1",
  system_access_token_expiration_in_seconds: "3000",
}
const params = {
  accountId: enterpriseAccountId,
  templateId: accountSettingsTemplateId,
  version: accountSettingsTemplateVersion,
  ifMatch: accountSettingsTemplateEtag,
  name: "Example-Account-Settings-Template",
  description: "IAM enterprise account settings template example - updated",
  accountSettings: settings,
}
try {
  const res = await iamIdentityService.updateAccountSettingsTemplateVersion(params);
  accountSettingsTemplateEtag = res.headers.etag;
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

account_settings = {}
account_settings['mfa'] = 'LEVEL1'
account_settings['system_access_token_expiration_in_seconds'] = 3000

update_response = iam_identity_service.update_account_settings_template_version(
  account_id=enterprise_account_id,
  template_id=account_settings_template_id,
  version=str(account_settings_template_version),
  if_match=account_settings_template_etag,
  name='Example-Account-Settings-Template',
  description='IAM enterprise account settings template example - updated',
  account_settings=account_settings,
)
account_settings_template = update_response.get_result()
print('\nupdate_account_settings_template() response: ', json.dumps(account_settings_template, indent=2))
Copy to clipboard

Response

Response Body

AccountSettingsTemplateResponse

Response body format for account settings template REST requests

AccountSettingsTemplateResponse

Response body format for account settings template REST requests.

AccountSettingsTemplateResponse

Response body format for account settings template REST requests.

AccountSettingsTemplateResponse

Response body format for account settings template REST requests.

AccountSettingsTemplateResponse

Response body format for account settings template REST requests.

Status Code

200
Successful updated template
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

Example responses

Status 200

{
  "id": "AccountSettingsTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9",
  "version": 1,
  "account_id": "5bbe28be34524sdbdaa34d37d1f2294a",
  "name": "my template name",
  "committed": false,
  "account_settings": {
    "restrict_create_platform_apikey": "RESTRICTED",
    "restrict_create_service_id": "NOT_RESTRICTED",
    "max_sessions_per_identity": "5",
    "mfa": "LEVEL3"
  },
  "created_at": "2023-03-07T13:55:33:428+0000",
  "created_by_id": "IBMid-12345678901",
  "last_modified_at": "2023-03-07T13:55:33:428+0000",
  "last_modified_by_id": "IBMid-12345678901",
  "entity_tag": "1-2da85a8f1172fc3527378318d3182778",
  "crn": "crn:v1:bluemix:public:iam-identity::a/5bbe28be34524sdbdaa34d37d1f2294a::template:AccountSettingsTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9"
}
Copy to clipboard

Success example

{
  "id": "AccountSettingsTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9",
  "version": 1,
  "account_id": "5bbe28be34524sdbdaa34d37d1f2294a",
  "name": "my template name",
  "committed": false,
  "account_settings": {
    "restrict_create_platform_apikey": "RESTRICTED",
    "restrict_create_service_id": "NOT_RESTRICTED",
    "max_sessions_per_identity": "5",
    "mfa": "LEVEL3"
  },
  "created_at": "2023-03-07T13:55:33:428+0000",
  "created_by_id": "IBMid-12345678901",
  "last_modified_at": "2023-03-07T13:55:33:428+0000",
  "last_modified_by_id": "IBMid-12345678901",
  "entity_tag": "1-2da85a8f1172fc3527378318d3182778",
  "crn": "crn:v1:bluemix:public:iam-identity::a/5bbe28be34524sdbdaa34d37d1f2294a::template:AccountSettingsTemplate-767fc1f6-c77c-4196-b3d6-a009a5a536e9"
}
Copy to clipboard

Delete a specific version of an account settings template in an Enterprise Account

Delete a specific version of an account settings template in an Enterprise Account.

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

(iamIdentity *IamIdentityV1) DeleteAccountSettingsTemplateVersion(deleteAccountSettingsTemplateVersionOptions *DeleteAccountSettingsTemplateVersionOptions) (response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) DeleteAccountSettingsTemplateVersionWithContext(ctx context.Context, deleteAccountSettingsTemplateVersionOptions *DeleteAccountSettingsTemplateVersionOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> deleteAccountSettingsTemplateVersion(DeleteAccountSettingsTemplateVersionOptions deleteAccountSettingsTemplateVersionOptions)
Copy to clipboard

deleteAccountSettingsTemplateVersion(params)

delete_account_settings_template_version(
        self,
        template_id: str,
        version: str,
        **kwargs,
    ) -> DetailedResponse

Authorization

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

iam-identity.account-settings-template.delete

Request

Instantiate the DeleteAccountSettingsTemplateVersionOptions struct and set the fields to provide parameter values for the DeleteAccountSettingsTemplateVersion method.

Use the DeleteAccountSettingsTemplateVersionOptions.Builder to create a DeleteAccountSettingsTemplateVersionOptions object that contains the parameter values for the deleteAccountSettingsTemplateVersion method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

template_id
Required*
string
ID of the account settings template
version
Required*
string
Version of the account settings template

parameter

WithContext method only

DeleteAccountSettingsTemplateVersionOptions

The DeleteAccountSettingsTemplateVersion options.

DeleteAccountSettingsTemplateVersionOptions

The deleteAccountSettingsTemplateVersion options.

parameters

templateId
Required*
string
ID of the account settings template.
version
Required*
string
Version of the account settings template.

parameters

template_id
Required*
str
ID of the account settings template.
version
Required*
str
Version of the account settings template.

Example request

curl -X DELETE "https://iam.cloud.ibm.com/v1/account_settings_templates/{template_id}/versions/{version}" --header "Content-Type: application/json" --header "Authorization: Bearer $TOKEN" 
Copy to clipboard

Example request

deleteOptions := &iamidentityv1.DeleteAccountSettingsTemplateVersionOptions{
  TemplateID: &accountSettingsTemplateId,
  Version:    core.StringPtr("1"),
}

response, err := iamIdentityService.DeleteAccountSettingsTemplateVersion(deleteOptions)

Example request

DeleteAccountSettingsTemplateVersionOptions deleteOptions = new DeleteAccountSettingsTemplateVersionOptions.Builder()
    .templateId(accountSettingsTemplateId)
    .version("1")
    .build();

Response<Void> deleteResponse = service.deleteAccountSettingsTemplateVersion(deleteOptions).execute();

Example request

const params = {
  templateId: accountSettingsTemplateId,
  version: 1,
}
try {
  const res = await iamIdentityService.deleteAccountSettingsTemplateVersion(params);
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

delete_response = iam_identity_service.delete_account_settings_template_version(
  template_id=account_settings_template_id, version='1'
)

Response

Status Code

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

No Sample Response

This method does not specify any sample responses.

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.

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

(iamIdentity *IamIdentityV1) CommitAccountSettingsTemplate(commitAccountSettingsTemplateOptions *CommitAccountSettingsTemplateOptions) (response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) CommitAccountSettingsTemplateWithContext(ctx context.Context, commitAccountSettingsTemplateOptions *CommitAccountSettingsTemplateOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> commitAccountSettingsTemplate(CommitAccountSettingsTemplateOptions commitAccountSettingsTemplateOptions)
Copy to clipboard

commitAccountSettingsTemplate(params)

commit_account_settings_template(
        self,
        template_id: str,
        version: str,
        **kwargs,
    ) -> DetailedResponse

Authorization

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

iam-identity.account-settings-template.update

Request

Instantiate the CommitAccountSettingsTemplateOptions struct and set the fields to provide parameter values for the CommitAccountSettingsTemplate method.

Use the CommitAccountSettingsTemplateOptions.Builder to create a CommitAccountSettingsTemplateOptions object that contains the parameter values for the commitAccountSettingsTemplate method.

Custom Headers

Authorization
Required*
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

template_id
Required*
string
ID of the account settings template
version
Required*
string
Version of the account settings template

parameter

WithContext method only

CommitAccountSettingsTemplateOptions

The CommitAccountSettingsTemplate options.

CommitAccountSettingsTemplateOptions

The commitAccountSettingsTemplate options.

parameters

templateId
Required*
string
ID of the account settings template.
version
Required*
string
Version of the account settings template.

parameters

template_id
Required*
str
ID of the account settings template.
version
Required*
str
Version of the account settings template.

Example request

curl -X POST "https://iam.cloud.ibm.com/v1/account_settings_templates/{template_id}/versions/{version}/commit" --header "Content-Type: application/json" --header "Authorization: Bearer $TOKEN" 
Copy to clipboard

Example request

commitOptions := &iamidentityv1.CommitAccountSettingsTemplateOptions{
  TemplateID: &accountSettingsTemplateId,
  Version:    core.StringPtr(strconv.FormatInt(accountSettingsTemplateVersion, 10)),
}

response, err := iamIdentityService.CommitAccountSettingsTemplate(commitOptions)

Example request

CommitAccountSettingsTemplateOptions commitOptions = new CommitAccountSettingsTemplateOptions.Builder()
    .templateId(accountSettingsTemplateId)
    .version(Long.toString(accountSettingsTemplateVersion))
    .build();

Response<Void> commitResponse = service.commitAccountSettingsTemplate(commitOptions).execute();

Example request

const commitParams = {
  templateId: accountSettingsTemplateId,
  version: accountSettingsTemplateVersion,
}
try {
  const res = await iamIdentityService.commitAccountSettingsTemplate(commitParams);
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

commit_response = iam_identity_service.commit_account_settings_template(
  template_id=account_settings_template_id, version=str(account_settings_template_version)
)

Response

Status Code

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

No Sample Response

This method does not specify any sample responses.

List account settings assignments.

GET /v1/account_settings_assignments/

(iamIdentity *IamIdentityV1) ListAccountSettingsAssignments(listAccountSettingsAssignmentsOptions *ListAccountSettingsAssignmentsOptions) (result *TemplateAssignmentListResponse, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) ListAccountSettingsAssignmentsWithContext(ctx context.Context, listAccountSettingsAssignmentsOptions *ListAccountSettingsAssignmentsOptions) (result *TemplateAssignmentListResponse, response *core.DetailedResponse, err error)

ServiceCall<TemplateAssignmentListResponse> listAccountSettingsAssignments(ListAccountSettingsAssignmentsOptions listAccountSettingsAssignmentsOptions)
Copy to clipboard

listAccountSettingsAssignments(params)

list_account_settings_assignments(
        self,
        *,
        account_id: Optional[str] = None,
        template_id: Optional[str] = None,
        template_version: Optional[str] = None,
        target: Optional[str] = None,
        target_type: Optional[str] = None,
        limit: Optional[int] = None,
        pagetoken: Optional[str] = None,
        sort: Optional[str] = None,
        order: Optional[str] = None,
        include_history: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.account-settings-assignment.read

Request

Instantiate the ListAccountSettingsAssignmentsOptions struct and set the fields to provide parameter values for the ListAccountSettingsAssignments method.

Use the ListAccountSettingsAssignmentsOptions.Builder to create a ListAccountSettingsAssignmentsOptions object that contains the parameter values for the listAccountSettingsAssignments method.

Custom Headers

Authorization
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

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

Allowable values: [Account,AccountGroup]
limit
integer
Optional size of a single page. Default is 20 items per page. Valid range is 1 to 100

Possible values: 1 ≤ value ≤ 100
Default: 20
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

Allowable values: [template_id,created_at,last_modified_at]
Default: created_at
order
string
Sort order

Allowable values: [asc,desc]
Default: asc
include_history
boolean
Defines if the entity history is included in the response

Default: false

parameter

WithContext method only

ListAccountSettingsAssignmentsOptions

The ListAccountSettingsAssignments options.

ListAccountSettingsAssignmentsOptions

The listAccountSettingsAssignments options.

parameters

accountId
string
Account ID of the Assignments to query. This parameter is required unless using a pagetoken.
templateId
string
Filter results by Template Id.
templateVersion
string
Filter results Template Version.
target
string
Filter results by the assignment target.
targetType
string
Filter results by the assignment's target type.

Allowable values: [Account,AccountGroup]
limit
number
Optional size of a single page. Default is 20 items per page. Valid range is 1 to 100.

Possible values: 1 ≤ value ≤ 100
Default: 20
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.

Allowable values: [template_id,created_at,last_modified_at]
Default: created_at
order
string
Sort order.

Allowable values: [asc,desc]
Default: asc
includeHistory
boolean
Defines if the entity history is included in the response.

Default: false

parameters

account_id
str
Account ID of the Assignments to query. This parameter is required unless using a pagetoken.
template_id
str
Filter results by Template Id.
template_version
str
Filter results Template Version.
target
str
Filter results by the assignment target.
target_type
str
Filter results by the assignment's target type.

Allowable values: [Account,AccountGroup]
limit
int
Optional size of a single page. Default is 20 items per page. Valid range is 1 to 100.

Possible values: 1 ≤ value ≤ 100
Default: 20
pagetoken
str
Optional Prev or Next page token returned from a previous query execution. Default is start with first page.
sort
str
If specified, the items are sorted by the value of this property.

Allowable values: [template_id,created_at,last_modified_at]
Default: created_at
order
str
Sort order.

Allowable values: [asc,desc]
Default: asc
include_history
bool
Defines if the entity history is included in the response.

Default: false

Example request

curl -X GET "https://iam.cloud.ibm.com/v1/account_settings_assignments?account_id=5bbe28be34524sdbdaa34d37d1f2294a" --header "Content-Type: application/json" --header "Authorization: Bearer $TOKEN" 
Copy to clipboard

Example request

listOptions := &iamidentityv1.ListAccountSettingsAssignmentsOptions{
  AccountID:  &enterpriseAccountID,
  TemplateID: &accountSettingsTemplateId,
}

listResponse, response, err := iamIdentityService.ListAccountSettingsAssignments(listOptions)

b, _ := json.MarshalIndent(listResponse, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

ListAccountSettingsTemplatesOptions listOptions = new ListAccountSettingsTemplatesOptions.Builder()
    .accountId(enterpriseAccountId)
    .build();

Response<AccountSettingsTemplateList> listResponse = service.listAccountSettingsTemplates(listOptions).execute();
AccountSettingsTemplateList listResult = listResponse.getResult();

System.out.println(listResult);

Example request

const params = {
  accountId: enterpriseAccountId,
  templateId: accountSettingsTemplateId,
}
try {
  const res = await iamIdentityService.listAccountSettingsAssignments(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

list_response = iam_identity_service.list_account_settings_assignments(
  account_id=enterprise_account_id, template_id=account_settings_template_id
)
assignment_list = list_response.get_result()
print('\ncreate_account_settings_assignment() response: ', json.dumps(assignment_list, indent=2))
Copy to clipboard

Response

Response Body

TemplateAssignmentListResponse

List Response body format for Template Assignments Records

TemplateAssignmentListResponse

List Response body format for Template Assignments Records.

TemplateAssignmentListResponse

List Response body format for Template Assignments Records.

TemplateAssignmentListResponse

List Response body format for Template Assignments Records.

TemplateAssignmentListResponse

List Response body format for Template Assignments Records.

Status Code

200
Successful Template retrieval
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

Example responses

Status 200

{
  "offset": 0,
  "limit": 20,
  "first": "https://iam.cloud.ibm.com/v1/account_settings_assignments?account_id=5bbe28be34524sdbdaa34d37d1f2294a",
  "assignments": [
    {
      "id": "TemplateAssignment-3bbfaa70-ec17-4c92-b81f-acfd013695a0",
      "account_id": "5bbe28be34524e88a34d37d1f2294a8a",
      "template_id": "AccountSettingsTemplate-cac1b203-5956-4981-bdec-0a4af4feab4d",
      "template_version": 1,
      "target_type": "Account",
      "target": "5bbe28be34524e88a34d37d1f2294a8a",
      "status": "succeeded",
      "created_at": "2023-05-09T13:01:27:946+0000",
      "created_by_id": "IBMid-550005G0RQ",
      "last_modified_at": "2023-05-09T13:10:04:480+0000",
      "last_modified_by_id": "IBMid-550005G0RQ",
      "entity_tag": "1-a0b520d828d9c0483aa2b623db8d09e6"
    }
  ]
}
Copy to clipboard

Success example

{
  "offset": 0,
  "limit": 20,
  "first": "https://iam.cloud.ibm.com/v1/account_settings_assignments?account_id=5bbe28be34524sdbdaa34d37d1f2294a",
  "assignments": [
    {
      "id": "TemplateAssignment-3bbfaa70-ec17-4c92-b81f-acfd013695a0",
      "account_id": "5bbe28be34524e88a34d37d1f2294a8a",
      "template_id": "AccountSettingsTemplate-cac1b203-5956-4981-bdec-0a4af4feab4d",
      "template_version": 1,
      "target_type": "Account",
      "target": "5bbe28be34524e88a34d37d1f2294a8a",
      "status": "succeeded",
      "created_at": "2023-05-09T13:01:27:946+0000",
      "created_by_id": "IBMid-550005G0RQ",
      "last_modified_at": "2023-05-09T13:10:04:480+0000",
      "last_modified_by_id": "IBMid-550005G0RQ",
      "entity_tag": "1-a0b520d828d9c0483aa2b623db8d09e6"
    }
  ]
}
Copy to clipboard

Create an assigment for an account settings template.

POST /v1/account_settings_assignments/

(iamIdentity *IamIdentityV1) CreateAccountSettingsAssignment(createAccountSettingsAssignmentOptions *CreateAccountSettingsAssignmentOptions) (result *TemplateAssignmentResponse, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) CreateAccountSettingsAssignmentWithContext(ctx context.Context, createAccountSettingsAssignmentOptions *CreateAccountSettingsAssignmentOptions) (result *TemplateAssignmentResponse, response *core.DetailedResponse, err error)

ServiceCall<TemplateAssignmentResponse> createAccountSettingsAssignment(CreateAccountSettingsAssignmentOptions createAccountSettingsAssignmentOptions)
Copy to clipboard

createAccountSettingsAssignment(params)

create_account_settings_assignment(
        self,
        template_id: str,
        template_version: int,
        target_type: str,
        target: str,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.account-settings-assignment.create

Request

Instantiate the CreateAccountSettingsAssignmentOptions struct and set the fields to provide parameter values for the CreateAccountSettingsAssignment method.

Use the CreateAccountSettingsAssignmentOptions.Builder to create a CreateAccountSettingsAssignmentOptions object that contains the parameter values for the createAccountSettingsAssignment method.

Custom Headers

Authorization
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Request Body

Required*

CreateTemplateAssignmentRequest

Body parameters to create an account settings template Assignment

parameter

WithContext method only

CreateAccountSettingsAssignmentOptions

The CreateAccountSettingsAssignment options.

CreateAccountSettingsAssignmentOptions

The createAccountSettingsAssignment options.

parameters

templateId
Required*
string
ID of the template to assign.
templateVersion
Required*
number
Version of the template to assign.

Possible values: value ≥ 1
targetType
Required*
string
Type of target to deploy to.

Allowable values: [Account,AccountGroup]
target
Required*
string
Identifier of target to deploy to.

parameters

template_id
Required*
str
ID of the template to assign.
template_version
Required*
int
Version of the template to assign.

Possible values: value ≥ 1
target_type
Required*
str
Type of target to deploy to.

Allowable values: [Account,AccountGroup]
target
Required*
str
Identifier of target to deploy to.

Example request

curl -X POST "https://iam.cloud.ibm.com/v1/account_settings_assignments" --header "Content-Type: application/json" --header "Authorization: Bearer $TOKEN" --data '{
    "template_id": "AccountSettingsTemplate-cac1b203-5956-4981-bdec-0a4af4feab4d",
    "template_version": 1,
    "target_type": "Account",
    "target": "5bbe28be34524e88a34d37d1f2294a8a"
}'
Copy to clipboard

Example request

assignOptions := &iamidentityv1.CreateAccountSettingsAssignmentOptions{
  TemplateID:      &accountSettingsTemplateId,
  TemplateVersion: &accountSettingsTemplateVersion,
  TargetType:      core.StringPtr("Account"),
  Target:          &enterpriseSubAccountID,
}

assignResponse, response, err := iamIdentityService.CreateAccountSettingsAssignment(assignOptions)

b, _ := json.MarshalIndent(assignResponse, "", "  ")
fmt.Println(string(b))

// Grab the Etag and id for use by other test methods.
accountSettingsTemplateAssignmentEtag = response.GetHeaders().Get("Etag")
accountSettingsTemplateAssignmentId = *assignResponse.ID
Copy to clipboard

Example request

CreateAccountSettingsAssignmentOptions assignOptions = new CreateAccountSettingsAssignmentOptions.Builder()
    .templateId(accountSettingsTemplateId)
    .templateVersion(accountSettingsTemplateVersion)
    .targetType("Account")
    .target(enterpriseSubAccountId)
    .build();

Response<TemplateAssignmentResponse> assignResponse = service.createAccountSettingsAssignment(assignOptions).execute();
TemplateAssignmentResponse assignmentResult = assignResponse.getResult();

// Save the id for use by other test methods.
accountSettingsTemplateAssignmentId = assignmentResult.getId();
// Grab the Etag value from the response for use in the update operation.
accountSettingsTemplateAssignmentEtag = assignResponse.getHeaders().values("Etag").get(0);

System.out.println(assignmentResult);
Copy to clipboard

Example request

const assignParams = {
  templateId: accountSettingsTemplateId,
  templateVersion: accountSettingsTemplateVersion,
  targetType: "Account",
  target: enterpriseSubAccountId,
}

try {
  const assRes = await iamIdentityService.createAccountSettingsAssignment(assignParams);
  const { result } = assRes;
  accountSettingsTemplateAssignmentId = result.id;
  accountSettingsTemplateAssignmentEtag= assRes.headers.etag;
  console.log(JSON.stringify(result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

assign_response = iam_identity_service.create_account_settings_assignment(
  template_id=account_settings_template_id,
  template_version=account_settings_template_version,
  target_type='Account',
  target=enterprise_subaccount_id,
)
assignment = assign_response.get_result()
print('\ncreate_account_settings_assignment() response: ', json.dumps(assignment, indent=2))
Copy to clipboard

Response

Response Body

TemplateAssignmentResponse

Response body format for Template Assignment Record

TemplateAssignmentResponse

Response body format for Template Assignment Record.

TemplateAssignmentResponse

Response body format for Template Assignment Record.

TemplateAssignmentResponse

Response body format for Template Assignment Record.

TemplateAssignmentResponse

Response body format for Template Assignment Record.

Status Code

202
Successful Assignment Record creation
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

Example responses

Status 202

{
  "id": "TemplateAssignment-3bbfaa70-ec17-4c92-b81f-acfd013695a0",
  "account_id": "5bbe28be34524e88a34d37d1f2294a8a",
  "template_id": "AccountSettingsTemplate-cac1b203-5956-4981-bdec-0a4af4feab4d",
  "template_version": 1,
  "target_type": "Account",
  "target": "5bbe28be34524e88a34d37d1f2294a8a",
  "status": "accepted",
  "created_at": "2023-05-09T13:01:27:946+0000",
  "created_by_id": "IBMid-550005G0RQ",
  "last_modified_at": "2023-05-09T13:10:04:480+0000",
  "last_modified_by_id": "IBMid-550005G0RQ",
  "entity_tag": "18-a0b520d828d9c0483aa2b623db8d09e6"
}
Copy to clipboard

Success example

{
  "id": "TemplateAssignment-3bbfaa70-ec17-4c92-b81f-acfd013695a0",
  "account_id": "5bbe28be34524e88a34d37d1f2294a8a",
  "template_id": "AccountSettingsTemplate-cac1b203-5956-4981-bdec-0a4af4feab4d",
  "template_version": 1,
  "target_type": "Account",
  "target": "5bbe28be34524e88a34d37d1f2294a8a",
  "status": "accepted",
  "created_at": "2023-05-09T13:01:27:946+0000",
  "created_by_id": "IBMid-550005G0RQ",
  "last_modified_at": "2023-05-09T13:10:04:480+0000",
  "last_modified_by_id": "IBMid-550005G0RQ",
  "entity_tag": "18-a0b520d828d9c0483aa2b623db8d09e6"
}
Copy to clipboard

Get an assigment for an account settings template.

GET /v1/account_settings_assignments/{assignment_id}

(iamIdentity *IamIdentityV1) GetAccountSettingsAssignment(getAccountSettingsAssignmentOptions *GetAccountSettingsAssignmentOptions) (result *TemplateAssignmentResponse, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) GetAccountSettingsAssignmentWithContext(ctx context.Context, getAccountSettingsAssignmentOptions *GetAccountSettingsAssignmentOptions) (result *TemplateAssignmentResponse, response *core.DetailedResponse, err error)

ServiceCall<TemplateAssignmentResponse> getAccountSettingsAssignment(GetAccountSettingsAssignmentOptions getAccountSettingsAssignmentOptions)
Copy to clipboard

getAccountSettingsAssignment(params)

get_account_settings_assignment(
        self,
        assignment_id: str,
        *,
        include_history: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.account-settings-assignment.read

Request

Instantiate the GetAccountSettingsAssignmentOptions struct and set the fields to provide parameter values for the GetAccountSettingsAssignment method.

Use the GetAccountSettingsAssignmentOptions.Builder to create a GetAccountSettingsAssignmentOptions object that contains the parameter values for the getAccountSettingsAssignment method.

Custom Headers

Authorization
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the 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

Default: false

parameter

WithContext method only

GetAccountSettingsAssignmentOptions

The GetAccountSettingsAssignment options.

GetAccountSettingsAssignmentOptions

The getAccountSettingsAssignment options.

parameters

assignmentId
Required*
string
ID of the Assignment Record.
includeHistory
boolean
Defines if the entity history is included in the response.

Default: false

parameters

assignment_id
Required*
str
ID of the Assignment Record.
include_history
bool
Defines if the entity history is included in the response.

Default: false

Example request

curl -X GET "https://iam.cloud.ibm.com/v1/account_settings_assignments/<assignment_id>" --header "Authorization: Bearer $TOKEN" 
Copy to clipboard

Example request

getAssignmentOptions := &iamidentityv1.GetAccountSettingsAssignmentOptions{
  AssignmentID: &accountSettingsTemplateAssignmentId,
}

assignment, response, err := iamIdentityService.GetAccountSettingsAssignment(getAssignmentOptions)

b, _ := json.MarshalIndent(assignment, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

GetAccountSettingsAssignmentOptions getOptions = new GetAccountSettingsAssignmentOptions.Builder()
    .assignmentId(accountSettingsTemplateAssignmentId)
    .build();

Response<TemplateAssignmentResponse> getResponse = service.getAccountSettingsAssignment(getOptions).execute();
TemplateAssignmentResponse getResult = getResponse.getResult();

// Grab the Etag value from the response for use in the update operation.
accountSettingsTemplateAssignmentEtag = getResponse.getHeaders().values("Etag").get(0);

System.out.println(getResult);
Copy to clipboard

Example request

response = iam_identity_service.get_account_settings_assignment(
  assignment_id=account_settings_template_assignment_id
)
assignment = response.get_result()
print('\nget_latest_account_settings_template_version response: ', json.dumps(assignment, indent=2))
Copy to clipboard

Response

Response Body

TemplateAssignmentResponse

Response body format for Template Assignment Record

TemplateAssignmentResponse

Response body format for Template Assignment Record.

TemplateAssignmentResponse

Response body format for Template Assignment Record.

TemplateAssignmentResponse

Response body format for Template Assignment Record.

TemplateAssignmentResponse

Response body format for Template Assignment Record.

Status Code

200
successful operation
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

Example responses

Status 200

{
  "id": "TemplateAssignment-3bbfaa70-ec17-4c92-b81f-acfd013695a0",
  "account_id": "5bbe28be34524e88a34d37d1f2294a8a",
  "template_id": "AccountSettingsTemplate-cac1b203-5956-4981-bdec-0a4af4feab4d",
  "template_version": 1,
  "target_type": "Account",
  "target": "5bbe28be34524e88a34d37d1f2294a8a",
  "status": "succeeded",
  "resources": [
    {
      "target": "5bbe28be34524e88a34d37d1f2294a8a",
      "account_settings": {
        "resource_created": {
          "id": "5bbe28be34524e88a34d37d1f2294a8a"
        },
        "status": "succeeded"
      }
    }
  ],
  "created_at": "2023-05-09T13:01:27:946+0000",
  "created_by_id": "IBMid-550005G0RQ",
  "last_modified_at": "2023-05-09T13:10:04:480+0000",
  "last_modified_by_id": "IBMid-550005G0RQ",
  "entity_tag": "1-a0b520d828d9c0483aa2b623db8d09e6"
}
Copy to clipboard

Success example

{
  "id": "TemplateAssignment-3bbfaa70-ec17-4c92-b81f-acfd013695a0",
  "account_id": "5bbe28be34524e88a34d37d1f2294a8a",
  "template_id": "AccountSettingsTemplate-cac1b203-5956-4981-bdec-0a4af4feab4d",
  "template_version": 1,
  "target_type": "Account",
  "target": "5bbe28be34524e88a34d37d1f2294a8a",
  "status": "succeeded",
  "resources": [
    {
      "target": "5bbe28be34524e88a34d37d1f2294a8a",
      "account_settings": {
        "resource_created": {
          "id": "5bbe28be34524e88a34d37d1f2294a8a"
        },
        "status": "succeeded"
      }
    }
  ],
  "created_at": "2023-05-09T13:01:27:946+0000",
  "created_by_id": "IBMid-550005G0RQ",
  "last_modified_at": "2023-05-09T13:10:04:480+0000",
  "last_modified_by_id": "IBMid-550005G0RQ",
  "entity_tag": "1-a0b520d828d9c0483aa2b623db8d09e6"
}
Copy to clipboard

Delete an account settings template assignment. This removes any IAM resources created by this assignment in child accounts.

DELETE /v1/account_settings_assignments/{assignment_id}

(iamIdentity *IamIdentityV1) DeleteAccountSettingsAssignment(deleteAccountSettingsAssignmentOptions *DeleteAccountSettingsAssignmentOptions) (result *ExceptionResponse, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) DeleteAccountSettingsAssignmentWithContext(ctx context.Context, deleteAccountSettingsAssignmentOptions *DeleteAccountSettingsAssignmentOptions) (result *ExceptionResponse, response *core.DetailedResponse, err error)

ServiceCall<ExceptionResponse> deleteAccountSettingsAssignment(DeleteAccountSettingsAssignmentOptions deleteAccountSettingsAssignmentOptions)
Copy to clipboard

deleteAccountSettingsAssignment(params)

delete_account_settings_assignment(
        self,
        assignment_id: str,
        **kwargs,
    ) -> DetailedResponse

Authorization

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

iam-identity.account-settings-assignment.delete

Request

Instantiate the DeleteAccountSettingsAssignmentOptions struct and set the fields to provide parameter values for the DeleteAccountSettingsAssignment method.

Use the DeleteAccountSettingsAssignmentOptions.Builder to create a DeleteAccountSettingsAssignmentOptions object that contains the parameter values for the deleteAccountSettingsAssignment method.

Custom Headers

Authorization
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

assignment_id
Required*
string
ID of the Assignment Record

parameter

WithContext method only

DeleteAccountSettingsAssignmentOptions

The DeleteAccountSettingsAssignment options.

DeleteAccountSettingsAssignmentOptions

The deleteAccountSettingsAssignment options.

parameters

assignmentId
Required*
string
ID of the Assignment Record.

parameters

assignment_id
Required*
str
ID of the Assignment Record.

Example request

curl -X DELETE "https://iam.cloud.ibm.com/v1/account_settings_assignments/<assignment_id>" --header "Authorization: Bearer $TOKEN" 
Copy to clipboard

Example request

deleteOptions := &iamidentityv1.DeleteAccountSettingsAssignmentOptions{
  AssignmentID: &accountSettingsTemplateAssignmentId,
}

excResponse, response, err := iamIdentityService.DeleteAccountSettingsAssignment(deleteOptions)

Example request

DeleteAccountSettingsAssignmentOptions deleteOptions = new DeleteAccountSettingsAssignmentOptions.Builder()
    .assignmentId(accountSettingsTemplateAssignmentId)
    .build();

Response<ExceptionResponse> deleteResponse = service.deleteAccountSettingsAssignment(deleteOptions).execute();

Example request

const params = {
  assignmentId: accountSettingsTemplateAssignmentId,
}
try {
  const res = await iamIdentityService.deleteAccountSettingsAssignment(params);
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

delete_response = iam_identity_service.delete_account_settings_assignment(
  assignment_id=account_settings_template_assignment_id
)

Response

Response Body

ExceptionResponse

Response body parameters in case of error situations.

ExceptionResponse

Response body parameters in case of error situations.

ExceptionResponse

Response body parameters in case of error situations.

ExceptionResponse

Response body parameters in case of error situations.

ExceptionResponse

Response body parameters in case of error situations.

Status Code

202
Request to delete assignment is accepted
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
Assignment not found
500
Internal Server error

No Sample Response

This method does not specify any sample responses.

Update an account settings assignment. Call this method to retry failed assignments or migrate the settings in child accounts to a new version.

PATCH /v1/account_settings_assignments/{assignment_id}

(iamIdentity *IamIdentityV1) UpdateAccountSettingsAssignment(updateAccountSettingsAssignmentOptions *UpdateAccountSettingsAssignmentOptions) (result *TemplateAssignmentResponse, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) UpdateAccountSettingsAssignmentWithContext(ctx context.Context, updateAccountSettingsAssignmentOptions *UpdateAccountSettingsAssignmentOptions) (result *TemplateAssignmentResponse, response *core.DetailedResponse, err error)

ServiceCall<TemplateAssignmentResponse> updateAccountSettingsAssignment(UpdateAccountSettingsAssignmentOptions updateAccountSettingsAssignmentOptions)
Copy to clipboard

updateAccountSettingsAssignment(params)

update_account_settings_assignment(
        self,
        assignment_id: str,
        if_match: str,
        template_version: int,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.account-settings-assignment.update

Request

Instantiate the UpdateAccountSettingsAssignmentOptions struct and set the fields to provide parameter values for the UpdateAccountSettingsAssignment method.

Use the UpdateAccountSettingsAssignmentOptions.Builder to create a UpdateAccountSettingsAssignmentOptions object that contains the parameter values for the updateAccountSettingsAssignment method.

Custom Headers

If-Match
Required*
string
Version of the assignment to be updated. Specify the version that you retrieved when reading the assignment. This value helps identifying parallel usage of this API. Pass * to indicate to update any version available. This might result in stale updates.
Authorization
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

assignment_id
Required*
string
ID of the Assignment Record

Request Body

Required*

UpdateTemplateAssignmentRequest

Request to update an assignment

parameter

WithContext method only

UpdateAccountSettingsAssignmentOptions

The UpdateAccountSettingsAssignment options.

UpdateAccountSettingsAssignmentOptions

The updateAccountSettingsAssignment options.

parameters

assignmentId
Required*
string
ID of the Assignment Record.
ifMatch
Required*
string
Version of the assignment to be updated. Specify the version that you retrieved when reading the assignment. This value helps identifying parallel usage of this API. Pass * to indicate to update any version available. This might result in stale updates.
templateVersion
Required*
number
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.

Possible values: value ≥ 1

parameters

assignment_id
Required*
str
ID of the Assignment Record.
if_match
Required*
str
Version of the assignment to be updated. Specify the version that you retrieved when reading the assignment. This value helps identifying parallel usage of this API. Pass * to indicate to update any version available. This might result in stale updates.
template_version
Required*
int
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.

Possible values: value ≥ 1

Example request

curl -X PATCH "https://iam.cloud.ibm.com/v1/account_settings_assignments/<assignment_id>" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" --header "Authorization: Bearer $TOKEN" --data '{
    "template_version": 2
}'
Copy to clipboard

Example request

updateOptions := &iamidentityv1.UpdateAccountSettingsAssignmentOptions{
  AssignmentID:    &accountSettingsTemplateAssignmentId,
  TemplateVersion: &accountSettingsTemplateVersion,
  IfMatch:         &accountSettingsTemplateAssignmentEtag,
}

updateResponse, response, err := iamIdentityService.UpdateAccountSettingsAssignment(updateOptions)

b, _ := json.MarshalIndent(updateResponse, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

UpdateAccountSettingsAssignmentOptions updateOptions = new UpdateAccountSettingsAssignmentOptions.Builder()
    .assignmentId(accountSettingsTemplateAssignmentId)
    .templateVersion(accountSettingsTemplateVersion)
    .ifMatch(accountSettingsTemplateAssignmentEtag)
    .build();

Response<TemplateAssignmentResponse> updateResponse = service.updateAccountSettingsAssignment(updateOptions).execute();
TemplateAssignmentResponse updateResult = updateResponse.getResult();

// Grab the Etag value from the response for use in the update operation.
accountSettingsTemplateAssignmentEtag = updateResponse.getHeaders().values("Etag").get(0);

System.out.println(updateResult);
Copy to clipboard

Example request

const assignParams = {
  assignmentId: accountSettingsTemplateAssignmentId,
  templateVersion: accountSettingsTemplateVersion,
  ifMatch: accountSettingsTemplateAssignmentEtag,
}

try {
  const assRes = await iamIdentityService.updateAccountSettingsAssignment(assignParams);
  console.log(JSON.stringify(assRes.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

assign_response = iam_identity_service.update_account_settings_assignment(
  assignment_id=account_settings_template_assignment_id,
  template_version=account_settings_template_version,
  if_match=account_settings_template_assignment_etag,
)
assignment = assign_response.get_result()
print('\nupdate_account_settings_template_assignment response: ', json.dumps(assignment, indent=2))
Copy to clipboard

Response

Response Body

TemplateAssignmentResponse

Response body format for Template Assignment Record

TemplateAssignmentResponse

Response body format for Template Assignment Record.

TemplateAssignmentResponse

Response body format for Template Assignment Record.

TemplateAssignmentResponse

Response body format for Template Assignment Record.

TemplateAssignmentResponse

Response body format for Template Assignment Record.

Status Code

200
successful operation
202
Successful Assignment Record update
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

Example responses

Status 200

{
  "id": "TemplateAssignment-3bbfaa70-ec17-4c92-b81f-acfd013695a0",
  "account_id": "5bbe28be34524e88a34d37d1f2294a8a",
  "template_id": "AccountSettingsTemplate-cac1b203-5956-4981-bdec-0a4af4feab4d",
  "template_version": 2,
  "target_type": "Account",
  "target": "5bbe28be34524e88a34d37d1f2294a8a",
  "status": "accepted",
  "created_at": "2023-05-09T13:01:27:946+0000",
  "created_by_id": "IBMid-550005G0RQ",
  "last_modified_at": "2023-05-09T13:10:04:480+0000",
  "last_modified_by_id": "IBMid-550005G0RQ",
  "entity_tag": "1-a0b520d828d9c0483aa2b623db8d09e6"
}
Copy to clipboard

Success example

{
  "id": "TemplateAssignment-3bbfaa70-ec17-4c92-b81f-acfd013695a0",
  "account_id": "5bbe28be34524e88a34d37d1f2294a8a",
  "template_id": "AccountSettingsTemplate-cac1b203-5956-4981-bdec-0a4af4feab4d",
  "template_version": 2,
  "target_type": "Account",
  "target": "5bbe28be34524e88a34d37d1f2294a8a",
  "status": "accepted",
  "created_at": "2023-05-09T13:01:27:946+0000",
  "created_by_id": "IBMid-550005G0RQ",
  "last_modified_at": "2023-05-09T13:10:04:480+0000",
  "last_modified_by_id": "IBMid-550005G0RQ",
  "entity_tag": "1-a0b520d828d9c0483aa2b623db8d09e6"
}
Copy to clipboard

List trusted profile template assignments.

GET /v1/profile_assignments/

(iamIdentity *IamIdentityV1) ListTrustedProfileAssignments(listTrustedProfileAssignmentsOptions *ListTrustedProfileAssignmentsOptions) (result *TemplateAssignmentListResponse, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) ListTrustedProfileAssignmentsWithContext(ctx context.Context, listTrustedProfileAssignmentsOptions *ListTrustedProfileAssignmentsOptions) (result *TemplateAssignmentListResponse, response *core.DetailedResponse, err error)

ServiceCall<TemplateAssignmentListResponse> listTrustedProfileAssignments(ListTrustedProfileAssignmentsOptions listTrustedProfileAssignmentsOptions)
Copy to clipboard

listTrustedProfileAssignments(params)

list_trusted_profile_assignments(
        self,
        *,
        account_id: Optional[str] = None,
        template_id: Optional[str] = None,
        template_version: Optional[str] = None,
        target: Optional[str] = None,
        target_type: Optional[str] = None,
        limit: Optional[int] = None,
        pagetoken: Optional[str] = None,
        sort: Optional[str] = None,
        order: Optional[str] = None,
        include_history: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.profile-assignment.read

Request

Instantiate the ListTrustedProfileAssignmentsOptions struct and set the fields to provide parameter values for the ListTrustedProfileAssignments method.

Use the ListTrustedProfileAssignmentsOptions.Builder to create a ListTrustedProfileAssignmentsOptions object that contains the parameter values for the listTrustedProfileAssignments method.

Custom Headers

Authorization
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

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

Allowable values: [Account,AccountGroup]
limit
integer
Optional size of a single page. Default is 20 items per page. Valid range is 1 to 100

Possible values: 1 ≤ value ≤ 100
Default: 20
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

Allowable values: [template_id,created_at,last_modified_at]
Default: created_at
order
string
Sort order

Allowable values: [asc,desc]
Default: asc
include_history
boolean
Defines if the entity history is included in the response

Default: false

parameter

WithContext method only

ListTrustedProfileAssignmentsOptions

The ListTrustedProfileAssignments options.

ListTrustedProfileAssignmentsOptions

The listTrustedProfileAssignments options.

parameters

accountId
string
Account ID of the Assignments to query. This parameter is required unless using a pagetoken.
templateId
string
Filter results by Template Id.
templateVersion
string
Filter results Template Version.
target
string
Filter results by the assignment target.
targetType
string
Filter results by the assignment's target type.

Allowable values: [Account,AccountGroup]
limit
number
Optional size of a single page. Default is 20 items per page. Valid range is 1 to 100.

Possible values: 1 ≤ value ≤ 100
Default: 20
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.

Allowable values: [template_id,created_at,last_modified_at]
Default: created_at
order
string
Sort order.

Allowable values: [asc,desc]
Default: asc
includeHistory
boolean
Defines if the entity history is included in the response.

Default: false

parameters

account_id
str
Account ID of the Assignments to query. This parameter is required unless using a pagetoken.
template_id
str
Filter results by Template Id.
template_version
str
Filter results Template Version.
target
str
Filter results by the assignment target.
target_type
str
Filter results by the assignment's target type.

Allowable values: [Account,AccountGroup]
limit
int
Optional size of a single page. Default is 20 items per page. Valid range is 1 to 100.

Possible values: 1 ≤ value ≤ 100
Default: 20
pagetoken
str
Optional Prev or Next page token returned from a previous query execution. Default is start with first page.
sort
str
If specified, the items are sorted by the value of this property.

Allowable values: [template_id,created_at,last_modified_at]
Default: created_at
order
str
Sort order.

Allowable values: [asc,desc]
Default: asc
include_history
bool
Defines if the entity history is included in the response.

Default: false

Example request

curl -X GET "https://iam.cloud.ibm.com/v1/profile_assignments?account_id=5bbe28be34524sdbdaa34d37d1f2294a" --header "Content-Type: application/json" --header "Authorization: Bearer $TOKEN" 
Copy to clipboard

Example request

listOptions := &iamidentityv1.ListTrustedProfileAssignmentsOptions{
  AccountID:  &enterpriseAccountID,
  TemplateID: &profileTemplateId,
}

listResponse, response, err := iamIdentityService.ListTrustedProfileAssignments(listOptions)

b, _ := json.MarshalIndent(listResponse, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

ListTrustedProfileAssignmentsOptions listOptions = new ListTrustedProfileAssignmentsOptions.Builder()
    .accountId(enterpriseAccountId)
    .templateId(profileTemplateId)
    .build();

Response<TemplateAssignmentListResponse> listResponse = service.listTrustedProfileAssignments(listOptions).execute();
TemplateAssignmentListResponse listResult = listResponse.getResult();
System.out.println(listResult);

Example request

const params = {
  accountId: enterpriseAccountId,
  templateId: profileTemplateId,
}
try {
  const res = await iamIdentityService.listTrustedProfileAssignments(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

list_response = iam_identity_service.list_trusted_profile_assignments(
  account_id=enterprise_account_id, template_id=profile_template_id
)
assignment_list = list_response.get_result()
print('\nlist_trusted_profile_assignments() response: ', json.dumps(assignment_list, indent=2))
Copy to clipboard

Response

Response Body

TemplateAssignmentListResponse

List Response body format for Template Assignments Records

TemplateAssignmentListResponse

List Response body format for Template Assignments Records.

TemplateAssignmentListResponse

List Response body format for Template Assignments Records.

TemplateAssignmentListResponse

List Response body format for Template Assignments Records.

TemplateAssignmentListResponse

List Response body format for Template Assignments Records.

Status Code

200
Successful Template retrieval
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

Example responses

Status 200

{
  "offset": 0,
  "limit": 20,
  "first": "https://iam.cloud.ibm.com/v1/profile_assignments?account_id=5bbe28be34524sdbdaa34d37d1f2294a",
  "assignments": [
    {
      "id": "TemplateAssignment-3bbfaa70-ec17-4c92-b81f-acfd013695a0",
      "account_id": "5bbe28be34524e88a34d37d1f2294a8a",
      "template_id": "ProfileTemplate-cac1b203-5956-4981-bdec-0a4af4feab4d",
      "template_version": 1,
      "target_type": "Account",
      "target": "5bbe28be34524e88a34d37d1f2294a8a",
      "status": "succeeded",
      "created_at": "2023-05-09T13:01:27:946+0000",
      "created_by_id": "IBMid-550005G0RQ",
      "last_modified_at": "2023-05-09T13:10:04:480+0000",
      "last_modified_by_id": "IBMid-550005G0RQ",
      "entity_tag": "1-a0b520d828d9c0483aa2b623db8d09e6"
    }
  ]
}
Copy to clipboard

Success example

{
  "offset": 0,
  "limit": 20,
  "first": "https://iam.cloud.ibm.com/v1/profile_assignments?account_id=5bbe28be34524sdbdaa34d37d1f2294a",
  "assignments": [
    {
      "id": "TemplateAssignment-3bbfaa70-ec17-4c92-b81f-acfd013695a0",
      "account_id": "5bbe28be34524e88a34d37d1f2294a8a",
      "template_id": "ProfileTemplate-cac1b203-5956-4981-bdec-0a4af4feab4d",
      "template_version": 1,
      "target_type": "Account",
      "target": "5bbe28be34524e88a34d37d1f2294a8a",
      "status": "succeeded",
      "created_at": "2023-05-09T13:01:27:946+0000",
      "created_by_id": "IBMid-550005G0RQ",
      "last_modified_at": "2023-05-09T13:10:04:480+0000",
      "last_modified_by_id": "IBMid-550005G0RQ",
      "entity_tag": "1-a0b520d828d9c0483aa2b623db8d09e6"
    }
  ]
}
Copy to clipboard

Create an assigment for a trusted profile template.

POST /v1/profile_assignments/

(iamIdentity *IamIdentityV1) CreateTrustedProfileAssignment(createTrustedProfileAssignmentOptions *CreateTrustedProfileAssignmentOptions) (result *TemplateAssignmentResponse, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) CreateTrustedProfileAssignmentWithContext(ctx context.Context, createTrustedProfileAssignmentOptions *CreateTrustedProfileAssignmentOptions) (result *TemplateAssignmentResponse, response *core.DetailedResponse, err error)

ServiceCall<TemplateAssignmentResponse> createTrustedProfileAssignment(CreateTrustedProfileAssignmentOptions createTrustedProfileAssignmentOptions)
Copy to clipboard

createTrustedProfileAssignment(params)

create_trusted_profile_assignment(
        self,
        template_id: str,
        template_version: int,
        target_type: str,
        target: str,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.profile-assignment.create

Request

Instantiate the CreateTrustedProfileAssignmentOptions struct and set the fields to provide parameter values for the CreateTrustedProfileAssignment method.

Use the CreateTrustedProfileAssignmentOptions.Builder to create a CreateTrustedProfileAssignmentOptions object that contains the parameter values for the createTrustedProfileAssignment method.

Custom Headers

Authorization
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Request Body

Required*

CreateTemplateAssignmentRequest

Body parameters to create an account settings template Assignment

parameter

WithContext method only

CreateTrustedProfileAssignmentOptions

The CreateTrustedProfileAssignment options.

CreateTrustedProfileAssignmentOptions

The createTrustedProfileAssignment options.

parameters

templateId
Required*
string
ID of the template to assign.
templateVersion
Required*
number
Version of the template to assign.

Possible values: value ≥ 1
targetType
Required*
string
Type of target to deploy to.

Allowable values: [Account,AccountGroup]
target
Required*
string
Identifier of target to deploy to.

parameters

template_id
Required*
str
ID of the template to assign.
template_version
Required*
int
Version of the template to assign.

Possible values: value ≥ 1
target_type
Required*
str
Type of target to deploy to.

Allowable values: [Account,AccountGroup]
target
Required*
str
Identifier of target to deploy to.

Example request

curl -X POST "https://iam.cloud.ibm.com/v1/profile_assignments" --header "Content-Type: application/json" --header "Authorization: Bearer $TOKEN" --data '{
    "template_id": "ProfileTemplate-cac1b203-5956-4981-bdec-0a4af4feab4d",
    "template_version": 1,
    "target_type": "Account",
    "target": "5bbe28be34524e88a34d37d1f2294a8a"
}'
Copy to clipboard

Example request

assignOptions := &iamidentityv1.CreateTrustedProfileAssignmentOptions{
  TemplateID:      &profileTemplateId,
  TemplateVersion: &profileTemplateVersion,
  TargetType:      core.StringPtr("Account"),
  Target:          &enterpriseSubAccountID,
}

assignResponse, response, err := iamIdentityService.CreateTrustedProfileAssignment(assignOptions)

b, _ := json.MarshalIndent(assignResponse, "", "  ")
fmt.Println(string(b))

// Grab the Etag and id for use by other test methods.
profileTemplateAssignmentEtag = response.GetHeaders().Get("Etag")
profileTemplateAssignmentId = *assignResponse.ID
Copy to clipboard

Example request

CreateTrustedProfileAssignmentOptions assignOptions = new CreateTrustedProfileAssignmentOptions.Builder()
    .templateId(profileTemplateId)
    .templateVersion(profileTemplateVersion)
    .targetType("Account")
    .target(enterpriseSubAccountId)
    .build();

Response<TemplateAssignmentResponse> assignResponse = service.createTrustedProfileAssignment(assignOptions).execute();
TemplateAssignmentResponse assignmentResponseResult = assignResponse.getResult();

// Save the id for use by other test methods.
profileTemplateAssignmentId = assignmentResponseResult.getId();
// Grab the Etag value from the response for use in the update operation.
profileTemplateAssignmentEtag = assignResponse.getHeaders().values("Etag").get(0);

System.out.println(assignmentResponseResult);
Copy to clipboard

Example request

const assignParams = {
  templateId: profileTemplateId,
  templateVersion: profileTemplateVersion,
  targetType: "Account",
  target: enterpriseSubAccountId,
}

try {
  const assRes = await iamIdentityService.createTrustedProfileAssignment(assignParams);
  const { result } = assRes;
  profileTemplateAssignmentId = result.id;
  profileTemplateAssignmentEtag= assRes.headers.etag;
  console.log(JSON.stringify(result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

assign_response = iam_identity_service.create_trusted_profile_assignment(
  template_id=profile_template_id,
  template_version=profile_template_version,
  target_type='Account',
  target=enterprise_subaccount_id,
)
assignment = assign_response.get_result()
print('\ncreate_trusted_profile_assignment() response: ', json.dumps(assignment, indent=2))
Copy to clipboard

Response

Response Body

TemplateAssignmentResponse

Response body format for Template Assignment Record

TemplateAssignmentResponse

Response body format for Template Assignment Record.

TemplateAssignmentResponse

Response body format for Template Assignment Record.

TemplateAssignmentResponse

Response body format for Template Assignment Record.

TemplateAssignmentResponse

Response body format for Template Assignment Record.

Status Code

202
Successful Assignment Record creation
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

Example responses

Status 202

{
  "id": "TemplateAssignment-3bbfaa70-ec17-4c92-b81f-acfd013695a0",
  "account_id": "5bbe28be34524e88a34d37d1f2294a8a",
  "template_id": "ProfileTemplate-cac1b203-5956-4981-bdec-0a4af4feab4d",
  "template_version": 1,
  "target_type": "Account",
  "target": "5bbe28be34524e88a34d37d1f2294a8a",
  "status": "accepted",
  "created_at": "2023-05-09T13:01:27:946+0000",
  "created_by_id": "IBMid-550005G0RQ",
  "last_modified_at": "2023-05-09T13:10:04:480+0000",
  "last_modified_by_id": "IBMid-550005G0RQ",
  "entity_tag": "18-a0b520d828d9c0483aa2b623db8d09e6"
}
Copy to clipboard

Success example

{
  "id": "TemplateAssignment-3bbfaa70-ec17-4c92-b81f-acfd013695a0",
  "account_id": "5bbe28be34524e88a34d37d1f2294a8a",
  "template_id": "ProfileTemplate-cac1b203-5956-4981-bdec-0a4af4feab4d",
  "template_version": 1,
  "target_type": "Account",
  "target": "5bbe28be34524e88a34d37d1f2294a8a",
  "status": "accepted",
  "created_at": "2023-05-09T13:01:27:946+0000",
  "created_by_id": "IBMid-550005G0RQ",
  "last_modified_at": "2023-05-09T13:10:04:480+0000",
  "last_modified_by_id": "IBMid-550005G0RQ",
  "entity_tag": "18-a0b520d828d9c0483aa2b623db8d09e6"
}
Copy to clipboard

Get an assigment for a trusted profile template.

GET /v1/profile_assignments/{assignment_id}

(iamIdentity *IamIdentityV1) GetTrustedProfileAssignment(getTrustedProfileAssignmentOptions *GetTrustedProfileAssignmentOptions) (result *TemplateAssignmentResponse, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) GetTrustedProfileAssignmentWithContext(ctx context.Context, getTrustedProfileAssignmentOptions *GetTrustedProfileAssignmentOptions) (result *TemplateAssignmentResponse, response *core.DetailedResponse, err error)

ServiceCall<TemplateAssignmentResponse> getTrustedProfileAssignment(GetTrustedProfileAssignmentOptions getTrustedProfileAssignmentOptions)
Copy to clipboard

getTrustedProfileAssignment(params)

get_trusted_profile_assignment(
        self,
        assignment_id: str,
        *,
        include_history: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.profile-assignment.read

Request

Instantiate the GetTrustedProfileAssignmentOptions struct and set the fields to provide parameter values for the GetTrustedProfileAssignment method.

Use the GetTrustedProfileAssignmentOptions.Builder to create a GetTrustedProfileAssignmentOptions object that contains the parameter values for the getTrustedProfileAssignment method.

Custom Headers

Authorization
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the 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

Default: false

parameter

WithContext method only

GetTrustedProfileAssignmentOptions

The GetTrustedProfileAssignment options.

GetTrustedProfileAssignmentOptions

The getTrustedProfileAssignment options.

parameters

assignmentId
Required*
string
ID of the Assignment Record.
includeHistory
boolean
Defines if the entity history is included in the response.

Default: false

parameters

assignment_id
Required*
str
ID of the Assignment Record.
include_history
bool
Defines if the entity history is included in the response.

Default: false

Example request

curl -X GET "https://iam.cloud.ibm.com/v1/profile_assignments/<assignment_id>" --header "Authorization: Bearer $TOKEN" 
Copy to clipboard

Example request

getAssignmentOptions := &iamidentityv1.GetTrustedProfileAssignmentOptions{
  AssignmentID: &profileTemplateAssignmentId,
}

assignment, response, err := iamIdentityService.GetTrustedProfileAssignment(getAssignmentOptions)

b, _ := json.MarshalIndent(assignment, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

GetTrustedProfileAssignmentOptions getOptions = new GetTrustedProfileAssignmentOptions.Builder()
    .assignmentId(profileTemplateAssignmentId)
    .build();

Response<TemplateAssignmentResponse> getResponse = service.getTrustedProfileAssignment(getOptions).execute();
TemplateAssignmentResponse getResult = getResponse.getResult();

System.out.println(getResult);

Example request

const params = {
  assignmentId: profileTemplateAssignmentId,
}
try {
  const res = await iamIdentityService.getTrustedProfileAssignment(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

response = iam_identity_service.get_trusted_profile_assignment(assignment_id=profile_template_assignment_id)
assignment = response.get_result()
print('\nget_trusted_profile_assignment() response: ', json.dumps(assignment, indent=2))
Copy to clipboard

Response

Response Body

TemplateAssignmentResponse

Response body format for Template Assignment Record

TemplateAssignmentResponse

Response body format for Template Assignment Record.

TemplateAssignmentResponse

Response body format for Template Assignment Record.

TemplateAssignmentResponse

Response body format for Template Assignment Record.

TemplateAssignmentResponse

Response body format for Template Assignment Record.

Status Code

200
successful operation
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

Example responses

Status 200

{
  "id": "TemplateAssignment-3bbfaa70-ec17-4c92-b81f-acfd013695a0",
  "account_id": "5bbe28be34524e88a34d37d1f2294a8a",
  "template_id": "ProfileTemplate-cac1b203-5956-4981-bdec-0a4af4feab4d",
  "template_version": 1,
  "target_type": "Account",
  "target": "5bbe28be34524e88a34d37d1f2294a8a",
  "status": "succeeded",
  "resources": [
    {
      "target": "5bbe28be34524e88a34d37d1f2294a8a",
      "profile": {
        "resource_created": {
          "id": "Profile-3bbfaa70-ec17-4c92-b81f-dfbda2a3"
        },
        "status": "succeeded"
      }
    }
  ],
  "created_at": "2023-05-09T13:01:27:946+0000",
  "created_by_id": "IBMid-550005G0RQ",
  "last_modified_at": "2023-05-09T13:10:04:480+0000",
  "last_modified_by_id": "IBMid-550005G0RQ",
  "entity_tag": "1-a0b520d828d9c0483aa2b623db8d09e6"
}
Copy to clipboard

Success example

{
  "id": "TemplateAssignment-3bbfaa70-ec17-4c92-b81f-acfd013695a0",
  "account_id": "5bbe28be34524e88a34d37d1f2294a8a",
  "template_id": "ProfileTemplate-cac1b203-5956-4981-bdec-0a4af4feab4d",
  "template_version": 1,
  "target_type": "Account",
  "target": "5bbe28be34524e88a34d37d1f2294a8a",
  "status": "succeeded",
  "resources": [
    {
      "target": "5bbe28be34524e88a34d37d1f2294a8a",
      "profile": {
        "resource_created": {
          "id": "Profile-3bbfaa70-ec17-4c92-b81f-dfbda2a3"
        },
        "status": "succeeded"
      }
    }
  ],
  "created_at": "2023-05-09T13:01:27:946+0000",
  "created_by_id": "IBMid-550005G0RQ",
  "last_modified_at": "2023-05-09T13:10:04:480+0000",
  "last_modified_by_id": "IBMid-550005G0RQ",
  "entity_tag": "1-a0b520d828d9c0483aa2b623db8d09e6"
}
Copy to clipboard

Delete a trusted profile assignment. This removes any IAM resources created by this assignment in child accounts.

DELETE /v1/profile_assignments/{assignment_id}

(iamIdentity *IamIdentityV1) DeleteTrustedProfileAssignment(deleteTrustedProfileAssignmentOptions *DeleteTrustedProfileAssignmentOptions) (result *ExceptionResponse, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) DeleteTrustedProfileAssignmentWithContext(ctx context.Context, deleteTrustedProfileAssignmentOptions *DeleteTrustedProfileAssignmentOptions) (result *ExceptionResponse, response *core.DetailedResponse, err error)

ServiceCall<ExceptionResponse> deleteTrustedProfileAssignment(DeleteTrustedProfileAssignmentOptions deleteTrustedProfileAssignmentOptions)
Copy to clipboard

deleteTrustedProfileAssignment(params)

delete_trusted_profile_assignment(
        self,
        assignment_id: str,
        **kwargs,
    ) -> DetailedResponse

Authorization

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

iam-identity.profile-assignment.delete

Request

Instantiate the DeleteTrustedProfileAssignmentOptions struct and set the fields to provide parameter values for the DeleteTrustedProfileAssignment method.

Use the DeleteTrustedProfileAssignmentOptions.Builder to create a DeleteTrustedProfileAssignmentOptions object that contains the parameter values for the deleteTrustedProfileAssignment method.

Custom Headers

Authorization
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

assignment_id
Required*
string
ID of the Assignment Record

parameter

WithContext method only

DeleteTrustedProfileAssignmentOptions

The DeleteTrustedProfileAssignment options.

DeleteTrustedProfileAssignmentOptions

The deleteTrustedProfileAssignment options.

parameters

assignmentId
Required*
string
ID of the Assignment Record.

parameters

assignment_id
Required*
str
ID of the Assignment Record.

Example request

curl -X DELETE "https://iam.cloud.ibm.com/v1/profile_assignments/<assignment_id>" --header "Authorization: Bearer $TOKEN" 
Copy to clipboard

Example request

deleteOptions := &iamidentityv1.DeleteTrustedProfileAssignmentOptions{
  AssignmentID: &profileTemplateAssignmentId,
}
excResponse, response, err := iamIdentityService.DeleteTrustedProfileAssignment(deleteOptions)

Example request

DeleteTrustedProfileAssignmentOptions deleteOptions = new DeleteTrustedProfileAssignmentOptions.Builder()
    .assignmentId(profileTemplateAssignmentId)
    .build();

Response<ExceptionResponse> deleteResponse = service.deleteTrustedProfileAssignment(deleteOptions).execute();

Example request

const params = {
  assignmentId: profileTemplateAssignmentId,
}
try {
  const res = await iamIdentityService.deleteTrustedProfileAssignment(params);
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

delete_response = iam_identity_service.delete_trusted_profile_assignment(
  assignment_id=profile_template_assignment_id
)

Response

Response Body

ExceptionResponse

Response body parameters in case of error situations.

ExceptionResponse

Response body parameters in case of error situations.

ExceptionResponse

Response body parameters in case of error situations.

ExceptionResponse

Response body parameters in case of error situations.

ExceptionResponse

Response body parameters in case of error situations.

Status Code

202
Request to delete assignment is accepted
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

No Sample Response

This method does not specify any sample responses.

Update a trusted profile assignment. Call this method to retry failed assignments or migrate the trusted profile in child accounts to a new version.

PATCH /v1/profile_assignments/{assignment_id}

(iamIdentity *IamIdentityV1) UpdateTrustedProfileAssignment(updateTrustedProfileAssignmentOptions *UpdateTrustedProfileAssignmentOptions) (result *TemplateAssignmentResponse, response *core.DetailedResponse, err error)

(iamIdentity *IamIdentityV1) UpdateTrustedProfileAssignmentWithContext(ctx context.Context, updateTrustedProfileAssignmentOptions *UpdateTrustedProfileAssignmentOptions) (result *TemplateAssignmentResponse, response *core.DetailedResponse, err error)

ServiceCall<TemplateAssignmentResponse> updateTrustedProfileAssignment(UpdateTrustedProfileAssignmentOptions updateTrustedProfileAssignmentOptions)
Copy to clipboard

updateTrustedProfileAssignment(params)

update_trusted_profile_assignment(
        self,
        assignment_id: str,
        if_match: str,
        template_version: int,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

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

iam-identity.profile-assignment.update

Request

Instantiate the UpdateTrustedProfileAssignmentOptions struct and set the fields to provide parameter values for the UpdateTrustedProfileAssignment method.

Use the UpdateTrustedProfileAssignmentOptions.Builder to create a UpdateTrustedProfileAssignmentOptions object that contains the parameter values for the updateTrustedProfileAssignment method.

Custom Headers

If-Match
Required*
string
Version of the Assignment to be updated. Specify the version that you retrieved when reading the Assignment. This value helps identifying parallel usage of this API. Pass * to indicate to update any version available. This might result in stale updates.
Authorization
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

assignment_id
Required*
string
ID of the Assignment Record

Request Body

Required*

UpdateTemplateAssignmentRequest

Request to update an assignment

parameter

WithContext method only

UpdateTrustedProfileAssignmentOptions

The UpdateTrustedProfileAssignment options.

UpdateTrustedProfileAssignmentOptions

The updateTrustedProfileAssignment options.

parameters

assignmentId
Required*
string
ID of the Assignment Record.
ifMatch
Required*
string
Version of the Assignment to be updated. Specify the version that you retrieved when reading the Assignment. This value helps identifying parallel usage of this API. Pass * to indicate to update any version available. This might result in stale updates.
templateVersion
Required*
number
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.

Possible values: value ≥ 1

parameters

assignment_id
Required*
str
ID of the Assignment Record.
if_match
Required*
str
Version of the Assignment to be updated. Specify the version that you retrieved when reading the Assignment. This value helps identifying parallel usage of this API. Pass * to indicate to update any version available. This might result in stale updates.
template_version
Required*
int
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.

Possible values: value ≥ 1

Example request

curl -X PATCH "https://iam.cloud.ibm.com/v1/profile_assignments/<assignment_id>" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" --data '{
    "template_version": 2
}'
Copy to clipboard

Example request

updateOptions := &iamidentityv1.UpdateTrustedProfileAssignmentOptions{
  AssignmentID:    &profileTemplateAssignmentId,
  TemplateVersion: &profileTemplateVersion,
  IfMatch:         &profileTemplateAssignmentEtag,
}

updateResponse, response, err := iamIdentityService.UpdateTrustedProfileAssignment(updateOptions)

b, _ := json.MarshalIndent(updateResponse, "", "  ")
fmt.Println(string(b))

// Grab the Etag and id for use by other test methods.
profileTemplateAssignmentEtag = response.GetHeaders().Get("Etag")
Copy to clipboard

Example request

UpdateTrustedProfileAssignmentOptions updateOptions = new UpdateTrustedProfileAssignmentOptions.Builder()
    .assignmentId(profileTemplateAssignmentId)
    .templateVersion(profileTemplateVersion)
    .ifMatch(profileTemplateAssignmentEtag)
    .build();

Response<TemplateAssignmentResponse> updateResponse = service.updateTrustedProfileAssignment(updateOptions).execute();
TemplateAssignmentResponse updateResult = updateResponse.getResult();

// Grab the Etag value from the response for use in the update operation.
profileTemplateAssignmentEtag = updateResponse.getHeaders().values("Etag").get(0);

System.out.println(updateResult);
Copy to clipboard

Example request

const assignParams = {
  assignmentId: profileTemplateAssignmentId,
  templateVersion: profileTemplateVersion,
  ifMatch: profileTemplateAssignmentEtag,
}

try {
  const assRes = await iamIdentityService.updateTrustedProfileAssignment(assignParams);
  console.log(JSON.stringify(assRes.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

assign_response = iam_identity_service.update_trusted_profile_assignment(
  assignment_id=profile_template_assignment_id,
  template_version=profile_template_version,
  if_match=profile_template_assignment_etag,
)
assignment = assign_response.get_result()
print('\nupdate_profile_template_assignment response: ', json.dumps(assignment, indent=2))
Copy to clipboard

Response

Response Body

TemplateAssignmentResponse

Response body format for Template Assignment Record

TemplateAssignmentResponse

Response body format for Template Assignment Record.

TemplateAssignmentResponse

Response body format for Template Assignment Record.

TemplateAssignmentResponse

Response body format for Template Assignment Record.

TemplateAssignmentResponse

Response body format for Template Assignment Record.

Status Code

200
successful operation
202
Successful Assignment Record update
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

Example responses

Status 200

{
  "id": "TemplateAssignment-3bbfaa70-ec17-4c92-b81f-acfd013695a0",
  "account_id": "5bbe28be34524e88a34d37d1f2294a8a",
  "template_id": "ProfileTemplate-cac1b203-5956-4981-bdec-0a4af4feab4d",
  "template_version": 2,
  "target_type": "Account",
  "target": "5bbe28be34524e88a34d37d1f2294a8a",
  "status": "accepted",
  "created_at": "2023-05-09T13:01:27:946+0000",
  "created_by_id": "IBMid-550005G0RQ",
  "last_modified_at": "2023-05-09T13:10:04:480+0000",
  "last_modified_by_id": "IBMid-550005G0RQ",
  "entity_tag": "1-a0b520d828d9c0483aa2b623db8d09e6"
}
Copy to clipboard

Success example

{
  "id": "TemplateAssignment-3bbfaa70-ec17-4c92-b81f-acfd013695a0",
  "account_id": "5bbe28be34524e88a34d37d1f2294a8a",
  "template_id": "ProfileTemplate-cac1b203-5956-4981-bdec-0a4af4feab4d",
  "template_version": 2,
  "target_type": "Account",
  "target": "5bbe28be34524e88a34d37d1f2294a8a",
  "status": "accepted",
  "created_at": "2023-05-09T13:01:27:946+0000",
  "created_by_id": "IBMid-550005G0RQ",
  "last_modified_at": "2023-05-09T13:10:04:480+0000",
  "last_modified_by_id": "IBMid-550005G0RQ",
  "entity_tag": "1-a0b520d828d9c0483aa2b623db8d09e6"
}
Copy to clipboard

Update one Identity Preference on scope 'account'.

PUT /v1/preferences/accounts/{account_id}/identities/{iam_id}/{service}/{preference_id}

Auditing

Calling this method generates the following auditing event.

iam-identity.preferences.update

Request

Custom Headers

Authorization
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

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

Request Body

Required*

UpdatePreferenceRequest

Request to create one identity preference on scope 'acount'.

Example request

curl -X PUT "https://iam.test.cloud.ibm.com/v1/preferences/accounts/ACCOUNT_ID/identities/IAM_ID/SERVICE/PREFERENCE_ID" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" 
Copy to clipboard

Response

Response Body

IdentityPreferenceResponse

Status Code

200
successful operation
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
preference not found
500
Internal Server error

Example responses

Status 200

{
  "service": "sample service",
  "id": "unique_id_of_preference",
  "account_id": "18e3020749ce4744b0b472466d61fdb4",
  "scope": "account",
  "value_string": "preference_value"
}
Copy to clipboard

Delete one Identity Preference on scope 'account'.

DELETE /v1/preferences/accounts/{account_id}/identities/{iam_id}/{service}/{preference_id}

Auditing

Calling this method generates the following auditing event.

iam-identity.preferences.update

Request

Custom Headers

Authorization
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the 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

Example request

curl -X DELETE "https://iam.test.cloud.ibm.com/v1/preferences/accounts/ACCOUNT_ID/identities/IAM_ID/SERVICE/PREFERENCE_ID" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" 
Copy to clipboard

Response

Response Body

ExceptionResponse

Response body parameters in case of error situations.

Status Code

204
Deleted Successful - no further details.
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
preference not found
500
Internal Server error

No Sample Response

This method does not specify any sample responses.

Get one Identity Preference on scope 'account'.

GET /v1/preferences/accounts/{account_id}/identities/{iam_id}/{service}/{preference_id}

Request

Custom Headers

Authorization
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the 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

Example request

curl -X GET "https://iam.test.cloud.ibm.com/v1/preferences/accounts/ACCOUNT_ID/identities/IAM_ID/SERVICE/PREFERENCE_ID" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" 
Copy to clipboard

Response

Response Body

IdentityPreferenceResponse

Status Code

200
successful operation
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
preference not found
500
Internal Server error

Example responses

Status 200

{
  "service": "sample service",
  "id": "unique_id_of_preference",
  "scope": "global",
  "value_string": "preference_value"
}
Copy to clipboard

Get all Identity Preferences for one account / user combination.

GET /v1/preferences/accounts/{account_id}/identities/{iam_id}

Request

Custom Headers

Authorization
string
Authorization Token used for the request. The supported token type is a Cloud IAM Access Token. If the token is omitted the request will fail with BXNIM0308E: 'No authorization header found'. Make sure that the provided token has the required authority for the request.

Path Parameters

account_id
Required*
string
Account id to get preferences for
iam_id
Required*
string
IAM id to get the preferences for

Example request

curl -X GET "https://iam.test.cloud.ibm.com/v1/preferences/accounts/ACCOUNT_ID/identities/IAM_ID" --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" 
Copy to clipboard

Response

Response Body

IdentityPreferencesResponse

Status Code

200
Successful - Get list of all Identity preferences for one account / user combination
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
User iam_id or account_id does not match Authorization token or not found.
500
Internal Server error

Example responses

Status 200

[
  {
    "service": "sample service1",
    "id": "unique_id_of_preference",
    "account_id": "18e3020749ce4744b0b472466d61fdb4",
    "scope": "account",
    "value_string": "preference_value"
  },
  {
    "service": "sample service2",
    "id": "unique_id_of_preference",
    "account_id": "18e3020749ce4744b0b472466d61fdb4",
    "scope": "account",
    "value_string": "preference_value"
  }
]
Copy to clipboard

Introduction

Endpoint URLs

Authentication

Auditing

Error handling

Additional headers

Methods

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

Authorization

Request

Custom Headers

Authorization

Query Parameters

account_id

iam_id

pagesize

pagetoken

scope

type

sort

order

include_history

parameter

ctx

ListApiKeysOptions

AccountID

IamID

Pagesize

Pagetoken

Scope

Type

Sort

Order

IncludeHistory

ListApiKeysOptions

accountId

iamId

pagesize

pagetoken

scope

type

sort

order

includeHistory

parameters

accountId

iamId

pagesize

pagetoken

scope

type

sort

order

includeHistory

parameters

account_id

iam_id

pagesize

pagetoken

scope

type

sort

order

include_history

Response

Response Body

apikeys

context

offset

limit

first

previous

next

ApiKeyList

Context

TransactionID

Operation

UserAgent

URL

InstanceID