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 iam 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 Logs service. Whenever an API method is called, an event is generated that you can then track and audit from within IBM Cloud Logs. The specific event type is listed for each individual method.

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

API Parameters

Some API parameter have additional details that need to be considered while using it in a request. Those API parameters are as follow:

When listing service IDs, trusted profiles or API keys you can filter the result set by providing an optional filter parameter. The exact syntax of this parameter is described below. Query syntax will follow the SCIM query syntax with reduced operator support. The value must be URL encoded. Only the following operators are supported.

Supported attribute operators-

sw - starts with
sw_ci - starts with ingnore case - non SCIM standard
ew - ends with
ew_ci - ends with ingnore case - non SCIM standard
co - contains
co_ci - contains ingnore case - non SCIM standard

Supported operators-
- and
- or
Grouping operators-
- ()
Data Values -Text
Sample
- name co "Foo" and description sw "Bar"

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,
        filter: 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.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
filter
string
An optional filter query parameter used to refine the results of the search operation. For more information see Filtering list results section.

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
filter
string
An optional filter query parameter used to refine the results of the search operation. For more information see Filtering list results section.

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
filter
str
An optional filter query parameter used to refine the results of the search operation. For more information see Filtering list results section.

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 = identityservice.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 whether you can manage CLI login sessions for the API key. When true, sessions are created and can be reviewed or revoked. When false, no sessions are tracked. To block access, delete or rotate the API key. Available only for user API keys.
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 whether you can manage CLI login sessions for the API key. When true, sessions are created and can be reviewed or revoked. When false, no sessions are tracked. To block access, delete or rotate the API key. Available only for user API keys.
action_when_leaked
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 = identityservice.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 = identityservice.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 = identityservice.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 whether you can manage CLI login sessions for the API key. When true, sessions are created and can be reviewed or revoked. When false, no sessions are tracked. To block access, delete or rotate the API key. Available only for user API keys.
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 whether you can manage CLI login sessions for the API key. When true, sessions are created and can be reviewed or revoked. When false, no sessions are tracked. To block access, delete or rotate the API key. Available only for user API keys.
action_when_leaked
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 = identityservice.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 = identityservice.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 = identityservice.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 = identityservice.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' -H 'Authorization: Bearer TOKEN' -H '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 = identityservice.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' -H 'Authorization: Bearer TOKEN' -H '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 = identityservice.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,
        filter: Optional[str] = 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
filter
string
An optional filter query parameter used to refine the results of the search operation. For more information see Filtering list results section.

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
filter
string
An optional filter query parameter used to refine the results of the search operation. For more information see Filtering list results section.

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
filter
str
An optional filter query parameter used to refine the results of the search operation. For more information see Filtering list results section.

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 = identityservice.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 = identityservice.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 = identityservice.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 = identityservice.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 = identityservice.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 = identityservice.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 = identityservice.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 = identityservice.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",
  "email": "user@ibm.com"
}
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",
  "email": "user@ibm.com"
}
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,
        filter: 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.
filter
string
An optional filter query parameter used to refine the results of the search operation. For more information see Filtering list results section.

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.
filter
string
An optional filter query parameter used to refine the results of the search operation. For more information see Filtering list results section.

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.
filter
str
An optional filter query parameter used to refine the results of the search operation. For more information see Filtering list results section.

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 = identityservice.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",
      "email": "user@ibm.com",
      "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",
      "email": "user@ibm.com",
      "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 = identityservice.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",
  "email": "user@ibm.com",
  "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",
  "email": "user@ibm.com",
  "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 = identityservice.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",
  "email": "user@ibm.com",
  "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",
  "email": "user@ibm.com",
  "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 = identityservice.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 = identityservice.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 = identityservice.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 = identityservice.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 = identityservice.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 = identityservice.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:bluemix: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:bluemix: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 = identityservice.createLink(createLinkOptions).execute();
ProfileLink linkResponse = response.getResult();
linkId = linkResponse.getId();

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

Example request

const CreateProfileLinkRequestLink = {
  crn: `crn:v1:bluemix: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:bluemix: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 = identityservice.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 = identityservice.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 = identityservice.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 = identityservice.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&quo

Introduction

Endpoint URLs

Authentication

Auditing

Error handling

Additional headers

API Parameters

Filtering list results

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

filter

parameter

ctx

ListApiKeysOptions

AccountID

IamID

Pagesize

Pagetoken

Scope

Type

Sort

Order

IncludeHistory

Filter

ListApiKeysOptions

accountId

iamId

pagesize

pagetoken

scope

type

sort

order

includeHistory

filter

parameters

accountId

iamId

pagesize

pagetoken

scope

type

sort

order

includeHistory

filter

parameters

account_id

iam_id

pagesize

pagetoken

scope

type

sort

order

include_history

filter

Response

Response Body

apikeys

context

offset

limit

first

previous

next