Introduction

The IAM Identity Service API is used to manage service IDs and API key identities and to create IAM access tokens for a user or service ID.

The code examples on this tab use the client library that is provided for Java.

Maven

<dependency>
    <groupId>com.ibm.cloud</groupId>
    <artifactId>platform-services</artifactId>
    <version>X.X.X</version>
</dependency>

Gradle

compile 'com.ibm.cloud:platform-services:${version}'

For more installation options, view this project in GitHub. https://github.com/IBM/platform-services-java-sdk

The code examples on this tab use the client library that is provided for Go.

Installation

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

For more installation options, view this project in GitHub. https://github.com/IBM/platform-services-go-sdk

The code examples on this tab use the client library that is provided for Node.js.

Installation

npm install ibm-platform-services

For more installation options, view this project in GitHub. https://github.com/IBM/platform-services-node-sdk

The code examples on this tab use the client library that is provided for Python.

Installation

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

For more installation options, view this project in GitHub. https://github.com/IBM/platform-services-python-sdk

Using the SDK

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.

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.

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.

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.

Endpoint URL

The IAM Identity Services API uses the following 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

Base URL

https://cloud.ibm.com

Authentication

Authorization to the Identity Services REST API is enforced by using an IAM access token. The token is used to determine the roles that the identity has access to when using various IAM API services. Use of the Identity Services REST API is done by adding a valid IAM Token to the HTTP Authorization request header.

The IAM actions that you need assigned are listed for each individual method. For more information about the required IAM actions and how they map to the access roles, see the documentation for the IAM Identity service.

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

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

To generate an access token from your API key, use the following cURL command.

curl -X POST \
  "https://iam.cloud.ibm.com/identity/token" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Accept: application/json' \
  --data-urlencode 'grant_type=urn:ibm:params:oauth:grant-type:apikey' \
  --data-urlencode 'apikey={api_key}'

Replace {api_key} with your IBM Cloud API key. To learn more, check out the IAM docs.

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.

For more information, see IAM authentication with the SDK.

For more information, see IAM authentication with the SDK.

For more information, see IAM authentication with the SDK.

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.

Event tracking

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

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

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.

Methods

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

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 that are bound to an entity they have access to. In case of service IDs and their API keys, a user must be either an account owner, a IBM Cloud org manager or IBM Cloud space developer in order to manage service IDs of the entity.

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 that are bound to an entity they have access to. In case of service IDs and their API keys, a user must be either an account owner, a IBM Cloud org manager or IBM Cloud space developer in order to manage service IDs of the entity.

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 that are bound to an entity they have access to. In case of service IDs and their API keys, a user must be either an account owner, a IBM Cloud org manager or IBM Cloud space developer in order to manage service IDs of the entity.

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 that are bound to an entity they have access to. In case of service IDs and their API keys, a user must be either an account owner, a IBM Cloud org manager or IBM Cloud space developer in order to manage service IDs of the entity.

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 that are bound to an entity they have access to. In case of service IDs and their API keys, a user must be either an account owner, a IBM Cloud org manager or IBM Cloud space developer in order to manage service IDs of the entity.

GET /v1/apikeys
(iamIdentity *IamIdentityV1) ListApiKeys(listApiKeysOptions *ListApiKeysOptions) (result *ApiKeyList, response *core.DetailedResponse, err error)
ServiceCall<ApiKeyList> listApiKeys(ListApiKeysOptions listApiKeysOptions)
listApiKeys(params)
list_api_keys(self,
        *,
        account_id: str = None,
        iam_id: str = None,
        pagesize: int = None,
        pagetoken: str = None,
        scope: str = None,
        type: str = None,
        sort: str = None,
        order: str = None,
        include_history: bool = None,
        **kwargs
    ) -> DetailedResponse

Authorization

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

  • iam-identity.apikey.list

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 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'. Please make sure that the provided token has the required authority for the request.

Query Parameters

  • Account ID of the API keys(s) 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 of the API key(s) 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.

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

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

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

    Allowable values: [entity,account]

    Default: entity

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

    Allowable values: [user,serviceid]

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

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

    Allowable values: [asc,desc]

    Default: asc

  • Defines if the entity history is included in the response.

    Default: false

The ListApiKeys options.

The listApiKeys options.

parameters

  • Account ID of the API keys(s) 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 of the API key(s) 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.

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

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

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

    Allowable values: [entity,account]

    Default: entity

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

    Allowable values: [user,serviceid]

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

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

    Allowable values: [asc,desc]

    Default: asc

  • Defines if the entity history is included in the response.

    Default: false

parameters

  • Account ID of the API keys(s) 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 of the API key(s) 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.

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

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

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

    Allowable values: [entity,account]

    Default: entity

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

    Allowable values: [user,serviceid]

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

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

    Allowable values: [asc,desc]

    Default: asc

  • Defines if the entity history is included in the response.

    Default: false

  • curl -X GET 'https://iam.cloud.ibm.com/v1/apikeys?account_id=ACCOUNT_ID&iam_id=IBMid-123WEREW' -H 'Authorization: Bearer TOKEN' -H 'Content-Type: application/json'
    
  • 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))
  • ListApiKeysOptions listApiKeysOptions = new ListApiKeysOptions.Builder()
        .accountId(accountId)
        .iamId(iamId)
        .includeHistory(true)
        .build();
    
    Response<ApiKeyList> response = service.listApiKeys(listApiKeysOptions).execute();
    ApiKeyList apiKeyList = response.getResult();
    System.out.println(apiKeyList.toString());
  • const params = {
      accountId: accountId,
      iamId: iamId,
      includeHistory: true,
    };
    
    iamIdentityService.listApiKeys(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err);
      });
  • 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))

Response

Response body format for the List API keys V1 REST request

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

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

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

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

Status Code

  • successful operation

  • Parameter validation failed

  • The incoming request did not contain a valid authentication information.

  • The incoming request did not contain a valid authentication information.

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

  • Internal Server error

Example responses
  • {
      "limit": 1,
      "first": {
        "href": "https://iam.cloud.ibm.com/v1/apikeys?pagetoken=PageToken"
      },
      "next": {
        "href": "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,
        "created_at": "2020-09-28T17:49+0000",
        "created_by": "IBMid-110000AB1Z",
        "modified_at": "2020-09-28T17:49+0000",
        "name": "apikeyNew",
        "description": "test",
        "iam_id": "IBMid-110000AB1Z",
        "account_id": "100abcde100a41abc100aza678abc0zz"
      }
    }
  • {
      "limit": 1,
      "first": {
        "href": "https://iam.cloud.ibm.com/v1/apikeys?pagetoken=PageToken"
      },
      "next": {
        "href": "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,
        "created_at": "2020-09-28T17:49+0000",
        "created_by": "IBMid-110000AB1Z",
        "modified_at": "2020-09-28T17:49+0000",
        "name": "apikeyNew",
        "description": "test",
        "iam_id": "IBMid-110000AB1Z",
        "account_id": "100abcde100a41abc100aza678abc0zz"
      }
    }

Create an API key

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 that are bound to an entity they have access to.

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 that are bound to an entity they have access to.

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 that are bound to an entity they have access to.

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 that are bound to an entity they have access to.

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 that are bound to an entity they have access to.

POST /v1/apikeys
(iamIdentity *IamIdentityV1) CreateApiKey(createApiKeyOptions *CreateApiKeyOptions) (result *ApiKey, response *core.DetailedResponse, err error)
ServiceCall<ApiKey> createApiKey(CreateApiKeyOptions createApiKeyOptions)
createApiKey(params)
create_api_key(self,
        name: str,
        iam_id: str,
        *,
        description: str = None,
        account_id: str = None,
        apikey: str = None,
        store_value: bool = None,
        entity_lock: str = None,
        **kwargs
    ) -> DetailedResponse

Authorization

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

  • iam-identity.apikey.create

Auditing

Calling this method generates the following events for the Activity Tracker with LogDNA service.

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 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'. Please make sure that the provided token has the required authority for the request.

  • Indicates if the API key is locked for further write operations. False by default.

    Default: false

Request to create an API key

The CreateApiKey options.

The createApiKey options.

parameters

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

  • The iam_id that this API key authenticates.

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

  • The account ID of the API key.

  • You can optionally passthrough the API key value for this API key. If passed, NO validation of that apiKey value is done, i.e. the value can be non-URL safe. 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. Please ensure enough variations when passing in this value.

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

  • Indicates if the API key is locked for further write operations. False by default.

    Default: false

parameters

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

  • The iam_id that this API key authenticates.

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

  • The account ID of the API key.

  • You can optionally passthrough the API key value for this API key. If passed, NO validation of that apiKey value is done, i.e. the value can be non-URL safe. 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. Please ensure enough variations when passing in this value.

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

  • Indicates if the API key is locked for further write operations. False by default.

    Default: false

  • curl -X POST 'https://iam.cloud.ibm.com/v1/apikeys' -H 'Authorization: Bearer TOKEN' -H 'Content-Type: application/json' -d '{
      "name": "My-apikey",
      "description": "my personal key",
      "iam_id": "IBMid-123WEREW",
      "account_id": "ACCOUNT_ID"
      "store_value": false
    }'
  • 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
  • CreateApiKeyOptions createApiKeyOptions = new CreateApiKeyOptions.Builder()
        .name(apiKeyName)
        .iamId(iamId)
        .description("Example ApiKey")
        .build();
    
    Response<ApiKey> response = service.createApiKey(createApiKeyOptions).execute();
    ApiKey apiKey = response.getResult();
    apikeyId = apiKey.getId();
    System.out.println(apiKey.toString());
  • const params = {
      name: apikeyName,
      iamId: iamId,
      description: 'Example ApiKey',
    };
    
    iamIdentityService.createApiKey(params)
      .then(res => {
        apikeyId = res.result.id
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err);
      });
  • api_key = iam_identity_service.create_api_key(
      name=apikey_name,
      iam_id=iam_id
    ).get_result()
    
    apikey_id = api_key['id']
    
    print(json.dumps(api_key, indent=2))

Response

Response body format for API key V1 REST requests

Response body format for API key V1 REST requests.

Response body format for API key V1 REST requests.

Response body format for API key V1 REST requests.

Response body format for API key V1 REST requests.

Status Code

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

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

  • The incoming request did not contain a valid authentication information.

  • The incoming request did not contain a valid authentication information.

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

  • Internal Server error. Response if unexpected error situation happened.

Example responses
  • {
      "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,
      "created_at": "2020-11-10T12:28+0000",
      "created_by": "IBMid-110000AB1Z",
      "modified_at": "2020-11-10T12:28+0000",
      "name": "apikey-test",
      "description": "apikey-test",
      "iam_id": "IBMid-110000AB1Z",
      "account_id": "100abcde100a41abc100aza678abc0zz",
      "apikey": "created_apikey"
    }
  • {
      "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,
      "created_at": "2020-11-10T12:28+0000",
      "created_by": "IBMid-110000AB1Z",
      "modified_at": "2020-11-10T12:28+0000",
      "name": "apikey-test",
      "description": "apikey-test",
      "iam_id": "IBMid-110000AB1Z",
      "account_id": "100abcde100a41abc100aza678abc0zz",
      "apikey": "created_apikey"
    }

Get details of an API key by its value

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 that are bound to an entity they have access to.

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 that are bound to an entity they have access to.

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 that are bound to an entity they have access to.

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 that are bound to an entity they have access to.

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 that are bound to an entity they have access to.

GET /v1/apikeys/details
(iamIdentity *IamIdentityV1) GetApiKeysDetails(getApiKeysDetailsOptions *GetApiKeysDetailsOptions) (result *ApiKey, response *core.DetailedResponse, err error)
ServiceCall<ApiKey> getApiKeysDetails(GetApiKeysDetailsOptions getApiKeysDetailsOptions)
getApiKeysDetails(params)
get_api_keys_details(self,
        *,
        iam_api_key: str = None,
        include_history: bool = None,
        **kwargs
    ) -> DetailedResponse

Authorization

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

  • iam-identity.apikey.get

Request

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

  • API key value.

  • 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'. Please make sure that the provided token has the required authority for the request.

Query Parameters

  • Defines if the entity history is included in the response

    Default: false

The GetApiKeysDetails options.

The getApiKeysDetails options.

parameters

  • API key value.

  • Defines if the entity history is included in the response.

    Default: false

parameters

  • API key value.

  • Defines if the entity history is included in the response.

    Default: false

  • curl -X GET 'https://iam.cloud.ibm.com/v1/apikeys/details' -H 'Authorization: Bearer TOKEN' -H 'IAM-Apikey: APIKEY_VALUE' -H 'Content-Type: application/json'
    
  • 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))
  • GetApiKeysDetailsOptions getApiKeysDetailsOptions = new GetApiKeysDetailsOptions.Builder()
        .iamApiKey(iamApiKey)
        .includeHistory(false)
        .build();
    
    Response<ApiKey> response = service.getApiKeysDetails(getApiKeysDetailsOptions).execute();
    ApiKey apiKey = response.getResult();
    System.out.println(apiKey.toString());
  • const params = {
      iamApiKey: iamApikey,
      includeHistory: false,
    };
    
    iamIdentityService.getApiKeysDetails(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err);
      });
  • 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 format for API key V1 REST requests

Response body format for API key V1 REST requests.

Response body format for API key V1 REST requests.

Response body format for API key V1 REST requests.

Response body format for API key V1 REST requests.

Status Code

  • Successful Get of API key details

  • Parameter validation failed

  • The incoming request did not contain a valid authentication information.

  • The incoming request did not contain a valid authentication information.

  • API key not found

  • Internal Server error

Example responses
  • {
      "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,
      "created_at": "2020-11-10T12:28+0000",
      "created_by": "IBMid-110000AB1Z",
      "modified_at": "2020-11-10T12:28+0000",
      "name": "apikey-test",
      "description": "apikey-test",
      "iam_id": "IBMid-110000AB1Z",
      "account_id": "100abcde100a41abc100aza678abc0zz"
    }
  • {
      "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,
      "created_at": "2020-11-10T12:28+0000",
      "created_by": "IBMid-110000AB1Z",
      "modified_at": "2020-11-10T12:28+0000",
      "name": "apikey-test",
      "description": "apikey-test",
      "iam_id": "IBMid-110000AB1Z",
      "account_id": "100abcde100a41abc100aza678abc0zz"
    }

Get details of an API key

Returns the details of an API key. Users can manage user API keys for themself, or service ID API keys for service IDs that are bound to an entity they have access to. In case of service IDs and their API keys, a user must be either an account owner, a IBM Cloud org manager or IBM Cloud space developer in order to manage service IDs of the entity.

Returns the details of an API key. Users can manage user API keys for themself, or service ID API keys for service IDs that are bound to an entity they have access to. In case of service IDs and their API keys, a user must be either an account owner, a IBM Cloud org manager or IBM Cloud space developer in order to manage service IDs of the entity.

Returns the details of an API key. Users can manage user API keys for themself, or service ID API keys for service IDs that are bound to an entity they have access to. In case of service IDs and their API keys, a user must be either an account owner, a IBM Cloud org manager or IBM Cloud space developer in order to manage service IDs of the entity.

Returns the details of an API key. Users can manage user API keys for themself, or service ID API keys for service IDs that are bound to an entity they have access to. In case of service IDs and their API keys, a user must be either an account owner, a IBM Cloud org manager or IBM Cloud space developer in order to manage service IDs of the entity.

Returns the details of an API key. Users can manage user API keys for themself, or service ID API keys for service IDs that are bound to an entity they have access to. In case of service IDs and their API keys, a user must be either an account owner, a IBM Cloud org manager or IBM Cloud space developer in order to manage service IDs of the entity.

GET /v1/apikeys/{id}
(iamIdentity *IamIdentityV1) GetApiKey(getApiKeyOptions *GetApiKeyOptions) (result *ApiKey, response *core.DetailedResponse, err error)
ServiceCall<ApiKey> getApiKey(GetApiKeyOptions getApiKeyOptions)
getApiKey(params)
get_api_key(self,
        id: str,
        *,
        include_history: bool = None,
        **kwargs
    ) -> DetailedResponse

Authorization

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

  • iam-identity.apikey.get

Request

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 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'. Please make sure that the provided token has the required authority for the request.

Path Parameters

  • Unique ID of the API key.

Query Parameters

  • Defines if the entity history is included in the response.

    Default: false

The GetApiKey options.

The getApiKey options.

parameters

  • Unique ID of the API key.

  • Defines if the entity history is included in the response.

    Default: false

parameters

  • Unique ID of the API key.

  • Defines if the entity history is included in the response.

    Default: false

  • curl -X GET 'https://iam.cloud.ibm.com/v1/apikeys/APIKEY_UNIQUE_ID' -H 'Authorization: Bearer TOKEN' -H 'Content-Type: application/json'
    
  • getApiKeyOptions := iamIdentityService.NewGetApiKeyOptions(apikeyID)
    
    apiKey, response, err := iamIdentityService.GetApiKey(getApiKeyOptions)
    if err != nil {
      panic(err)
    }
    apikeyEtag = response.GetHeaders().Get("Etag")
    b, _ := json.MarshalIndent(apiKey, "", "  ")
    fmt.Println(string(b))
  • GetApiKeyOptions getApiKeyOptions = new GetApiKeyOptions.Builder()
        .id(apikeyId)
        .includeHistory(true)
        .build();
    
    Response<ApiKey> response = service.getApiKey(getApiKeyOptions).execute();
    ApiKey apiKey = response.getResult();
    apikeyEtag = response.getHeaders().values("Etag").get(0);
    System.out.println(apiKey.toString());
  • const params = {
      id: apikeyId,
    };
    
    iamIdentityService.getApiKey(params)
      .then(res => {
        apikeyEtag = res.headers['etag'];
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err);
      });
  • response = iam_identity_service.get_api_key(
      id=apikey_id
    )
    
    apikey_etag = response.get_headers()['Etag']
    api_key = response.get_result()
    
    print(json.dumps(api_key, indent=2))

Response

Response body format for API key V1 REST requests

Response body format for API key V1 REST requests.

Response body format for API key V1 REST requests.

Response body format for API key V1 REST requests.

Response body format for API key V1 REST requests.

Status Code

  • Successful Get of API key

  • Parameter validation failed

  • The incoming request did not contain a valid authentication information.

  • The incoming request did not contain a valid authentication information.

  • API key with provided ID not found

  • Internal Server error

Example responses
  • {
      "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,
      "created_at": "2020-11-10T12:28+0000",
      "created_by": "IBMid-110000AB1Z",
      "modified_at": "2020-11-10T12:28+0000",
      "name": "apikey-test",
      "description": "apikey-test",
      "iam_id": "IBMid-110000AB1Z",
      "account_id": "100abcde100a41abc100aza678abc0zz"
    }
  • {
      "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,
      "created_at": "2020-11-10T12:28+0000",
      "created_by": "IBMid-110000AB1Z",
      "modified_at": "2020-11-10T12:28+0000",
      "name": "apikey-test",
      "description": "apikey-test",
      "iam_id": "IBMid-110000AB1Z",
      "account_id": "100abcde100a41abc100aza678abc0zz"
    }

Updates an API key

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 that are bound to an entity they have access to.

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 that are bound to an entity they have access to.

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 that are bound to an entity they have access to.

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 that are bound to an entity they have access to.

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 that are bound to an entity they have access to.

PUT /v1/apikeys/{id}
(iamIdentity *IamIdentityV1) UpdateApiKey(updateApiKeyOptions *UpdateApiKeyOptions) (result *ApiKey, response *core.DetailedResponse, err error)
ServiceCall<ApiKey> updateApiKey(UpdateApiKeyOptions updateApiKeyOptions)
updateApiKey(params)
update_api_key(self,
        id: str,
        if_match: str,
        *,
        name: str = None,
        description: str = None,
        **kwargs
    ) -> DetailedResponse

Authorization

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

  • iam-identity.apikey.update

Auditing

Calling this method generates the following events for the Activity Tracker with LogDNA service.

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

  • 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 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'. Please make sure that the provided token has the required authority for the request.

Path Parameters

  • Unique ID of the API key to be updated.

Request to update an API key

The UpdateApiKey options.

The updateApiKey options.

parameters

  • Unique ID of the API key to be updated.

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

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

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

parameters

  • Unique ID of the API key to be updated.

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

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

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

  • curl -X PUT 'https://iam.cloud.ibm.com/v1/apikeys/APIKEY_UNIQUE_ID' -H 'Authorization: Bearer TOKEN' -H 'If-Match: <value of etag header from GET request>' -H 'Content-Type: application/json' -d '{
      "name": "My-apikey",
      "description": "my personal key"
    }'
  • 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))
  • UpdateApiKeyOptions updateApiKeyOptions = new UpdateApiKeyOptions.Builder()
        .id(apikeyId)
        .ifMatch(apikeyEtag)
        .description("This is an updated description")
        .build();
    
    Response<ApiKey> response = service.updateApiKey(updateApiKeyOptions).execute();
    ApiKey apiKey = response.getResult();
    System.out.println(apiKey.toString());
  • const params = {
      id: apikeyId,
      ifMatch: apikeyEtag,
      description: 'This is an updated description',
    };
    
    iamIdentityService.updateApiKey(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err);
      });
  • 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))

Response

Response body format for API key V1 REST requests

Response body format for API key V1 REST requests.

Response body format for API key V1 REST requests.

Response body format for API key V1 REST requests.

Response body format for API key V1 REST requests.

Status Code

  • Successful - API key updated

  • Parameter validation failed

  • The incoming request did not contain a valid authentication information.

  • The incoming request did not contain a valid authentication information.

  • API key with provided parameters not found

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

  • Internal Server error

Example responses
  • {
      "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,
      "created_at": "2020-11-10T12:28+0000",
      "created_by": "IBMid-110000AB1Z",
      "modified_at": "2020-11-10T13:45+0000",
      "name": "Apikey-test1",
      "description": "Apikey-test1",
      "iam_id": "IBMid-110000AB1Z",
      "account_id": "100abcde100a41abc100aza678abc0zz"
    }
  • {
      "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,
      "created_at": "2020-11-10T12:28+0000",
      "created_by": "IBMid-110000AB1Z",
      "modified_at": "2020-11-10T13:45+0000",
      "name": "Apikey-test1",
      "description": "Apikey-test1",
      "iam_id": "IBMid-110000AB1Z",
      "account_id": "100abcde100a41abc100aza678abc0zz"
    }

Deletes an API key

Deletes an API key. Existing tokens will remain valid until expired. Refresh tokens will not work any more for this API key. Users can manage user API keys for themself, or service ID API keys for service IDs that are bound to an entity they have access to.

Deletes an API key. Existing tokens will remain valid until expired. Refresh tokens will not work any more for this API key. Users can manage user API keys for themself, or service ID API keys for service IDs that are bound to an entity they have access to.

Deletes an API key. Existing tokens will remain valid until expired. Refresh tokens will not work any more for this API key. Users can manage user API keys for themself, or service ID API keys for service IDs that are bound to an entity they have access to.

Deletes an API key. Existing tokens will remain valid until expired. Refresh tokens will not work any more for this API key. Users can manage user API keys for themself, or service ID API keys for service IDs that are bound to an entity they have access to.

Deletes an API key. Existing tokens will remain valid until expired. Refresh tokens will not work any more for this API key. Users can manage user API keys for themself, or service ID API keys for service IDs that are bound to an entity they have access to.

DELETE /v1/apikeys/{id}
(iamIdentity *IamIdentityV1) DeleteApiKey(deleteApiKeyOptions *DeleteApiKeyOptions) (response *core.DetailedResponse, err error)
ServiceCall<Void> deleteApiKey(DeleteApiKeyOptions deleteApiKeyOptions)
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.

  • iam-identity.apikey.delete

Auditing

Calling this method generates the following events for the Activity Tracker with LogDNA service.

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 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'. Please make sure that the provided token has the required authority for the request.

Path Parameters

  • Unique ID of the API key.

The DeleteApiKey options.

The deleteApiKey options.

parameters

  • Unique ID of the API key.

parameters

  • Unique ID of the API key.

  • curl -X DELETE 'https://iam.cloud.ibm.com/v1/apikeys/APIKEY_UNIQUE_ID' -H 'Authorization: Bearer TOKEN' -H 'Content-Type: application/json'
    
  • deleteApiKeyOptions := iamIdentityService.NewDeleteApiKeyOptions(apikeyID)
    
    response, err := iamIdentityService.DeleteApiKey(deleteApiKeyOptions)
    if err != nil {
      panic(err)
    }
  • DeleteApiKeyOptions deleteApiKeyOptions = new DeleteApiKeyOptions.Builder()
        .id(apikeyId)
        .build();
    
    service.deleteApiKey(deleteApiKeyOptions).execute();
  • const params = {
      id: apikeyId,
    };
    
    iamIdentityService.deleteApiKey(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err);
      });
  • response = iam_identity_service.delete_api_key(id=apikey_id)
    
    print(response)

Response

Status Code

  • Deleted Successful - no further details

  • The incoming request did not contain a valid authentication information.

  • The incoming request did not contain a valid authentication information.

  • API key with given ID not found

  • Conflict - ApiKey could not be deleted

  • Internal Server error

No Sample Response

This method does not specify any sample responses.

Lock the API key

Locks an API key by ID. Users can manage user API keys for themself, or service ID API keys for service IDs that are bound to an entity they have access to. In case of service IDs and their API keys, a user must be either an account owner, a IBM Cloud org manager or IBM Cloud space developer in order to manage service IDs of the entity.

Locks an API key by ID. Users can manage user API keys for themself, or service ID API keys for service IDs that are bound to an entity they have access to. In case of service IDs and their API keys, a user must be either an account owner, a IBM Cloud org manager or IBM Cloud space developer in order to manage service IDs of the entity.

Locks an API key by ID. Users can manage user API keys for themself, or service ID API keys for service IDs that are bound to an entity they have access to. In case of service IDs and their API keys, a user must be either an account owner, a IBM Cloud org manager or IBM Cloud space developer in order to manage service IDs of the entity.

Locks an API key by ID. Users can manage user API keys for themself, or service ID API keys for service IDs that are bound to an entity they have access to. In case of service IDs and their API keys, a user must be either an account owner, a IBM Cloud org manager or IBM Cloud space developer in order to manage service IDs of the entity.

Locks an API key by ID. Users can manage user API keys for themself, or service ID API keys for service IDs that are bound to an entity they have access to. In case of service IDs and their API keys, a user must be either an account owner, a IBM Cloud org manager or IBM Cloud space developer in order to manage service IDs of the entity.

POST /v1/apikeys/{id}/lock
(iamIdentity *IamIdentityV1) LockApiKey(lockApiKeyOptions *LockApiKeyOptions) (response *core.DetailedResponse, err error)
ServiceCall<Void> lockApiKey(LockApiKeyOptions lockApiKeyOptions)
lockApiKey(params)
lock_api_key(self,
        id: str,
        **kwargs
    ) -> DetailedResponse

Auditing

Calling this method generates the following events for the Activity Tracker with LogDNA service.

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 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'. Please make sure that the provided token has the required authority for the request.

Path Parameters

  • Unique ID of the API key.

The LockApiKey options.

The lockApiKey options.

parameters

  • Unique ID of the API key.

parameters

  • Unique ID of the API key.

  • curl -X POST 'https://iam.cloud.ibm.com/v1/apikeys/APIKEY_UNIQUE_ID/lock' -H 'Authorization: Bearer TOKEN' -H 'Content-Type: application/json'
    
  • lockApiKeyOptions := iamIdentityService.NewLockApiKeyOptions(apikeyID)
    
    response, err := iamIdentityService.LockApiKey(lockApiKeyOptions)
    if err != nil {
      panic(err)
    }
  • LockApiKeyOptions lockApiKeyOptions = new LockApiKeyOptions.Builder()
        .id(apikeyId)
        .build();
    
    service.lockApiKey(lockApiKeyOptions).execute();
  • const params = {
      id: apikeyId,
    };
    
    iamIdentityService.lockApiKey(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err);
      });
  • response = iam_identity_service.lock_api_key(id=apikey_id)
    
    print(response)

Response

Status Code

  • Successful locked

  • Parameter validation failed

  • The incoming request did not contain a valid authentication information.

  • The incoming request did not contain a valid authentication information.

  • API key with provided ID not found

  • Internal Server error

No Sample Response

This method does not specify any sample responses.

Unlock the API key

Unlocks an API key by ID. Users can manage user API keys for themself, or service ID API keys for service IDs that are bound to an entity they have access to. In case of service IDs and their API keys, a user must be either an account owner, a IBM Cloud org manager or IBM Cloud space developer in order to manage service IDs of the entity.

Unlocks an API key by ID. Users can manage user API keys for themself, or service ID API keys for service IDs that are bound to an entity they have access to. In case of service IDs and their API keys, a user must be either an account owner, a IBM Cloud org manager or IBM Cloud space developer in order to manage service IDs of the entity.

Unlocks an API key by ID. Users can manage user API keys for themself, or service ID API keys for service IDs that are bound to an entity they have access to. In case of service IDs and their API keys, a user must be either an account owner, a IBM Cloud org manager or IBM Cloud space developer in order to manage service IDs of the entity.

Unlocks an API key by ID. Users can manage user API keys for themself, or service ID API keys for service IDs that are bound to an entity they have access to. In case of service IDs and their API keys, a user must be either an account owner, a IBM Cloud org manager or IBM Cloud space developer in order to manage service IDs of the entity.

Unlocks an API key by ID. Users can manage user API keys for themself, or service ID API keys for service IDs that are bound to an entity they have access to. In case of service IDs and their API keys, a user must be either an account owner, a IBM Cloud org manager or IBM Cloud space developer in order to manage service IDs of the entity.

DELETE /v1/apikeys/{id}/lock
(iamIdentity *IamIdentityV1) UnlockApiKey(unlockApiKeyOptions *UnlockApiKeyOptions) (response *core.DetailedResponse, err error)
ServiceCall<Void> unlockApiKey(UnlockApiKeyOptions unlockApiKeyOptions)
unlockApiKey(params)
unlock_api_key(self,
        id: str,
        **kwargs
    ) -> DetailedResponse

Auditing

Calling this method generates the following events for the Activity Tracker with LogDNA service.

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 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'. Please make sure that the provided token has the required authority for the request.

Path Parameters

  • Unique ID of the API key.

The UnlockApiKey options.

The unlockApiKey options.

parameters

  • Unique ID of the API key.

parameters

  • Unique ID of the API key.

  • curl -X DELETE 'https://iam.cloud.ibm.com/v1/apikeys/APIKEY_UNIQUE_ID/lock' -H 'Authorization: Bearer TOKEN' -H 'Content-Type: application/json'
    
  • unlockApiKeyOptions := iamIdentityService.NewUnlockApiKeyOptions(apikeyID)
    
    response, err := iamIdentityService.UnlockApiKey(unlockApiKeyOptions)
    if err != nil {
      panic(err)
    }
  • UnlockApiKeyOptions unlockApiKeyOptions = new UnlockApiKeyOptions.Builder()
        .id(apikeyId)
        .build();
    
    service.unlockApiKey(unlockApiKeyOptions).execute();
  • const params = {
      id: apikeyId,
    };
    
    iamIdentityService.unlockApiKey(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err);
      });
  • response = iam_identity_service.unlock_api_key(id=apikey_id)
    
    print(response)

Response

Status Code

  • Successful unlocked

  • Parameter validation failed

  • The incoming request did not contain a valid authentication information.

  • The incoming request did not contain a valid authentication information.

  • API key with provided ID not found

  • Internal Server error

No Sample Response

This method does not specify any sample responses.

List service IDs

Returns a list of service IDs. Users can manage user API keys for themself, or service ID API keys for service IDs that are bound to an entity they have access to.

Returns a list of service IDs. Users can manage user API keys for themself, or service ID API keys for service IDs that are bound to an entity they have access to.

Returns a list of service IDs. Users can manage user API keys for themself, or service ID API keys for service IDs that are bound to an entity they have access to.

Returns a list of service IDs. Users can manage user API keys for themself, or service ID API keys for service IDs that are bound to an entity they have access to.

Returns a list of service IDs. Users can manage user API keys for themself, or service ID API keys for service IDs that are bound to an entity they have access to.

GET /v1/serviceids/
(iamIdentity *IamIdentityV1) ListServiceIds(listServiceIdsOptions *ListServiceIdsOptions) (result *ServiceIdList, response *core.DetailedResponse, err error)
ServiceCall<ServiceIdList> listServiceIds(ListServiceIdsOptions listServiceIdsOptions)
listServiceIds(params)
list_service_ids(self,
        *,
        account_id: str = None,
        name: str = None,
        pagesize: int = None,
        pagetoken: str = None,
        sort: str = None,
        order: str = None,
        include_history: bool = None,
        **kwargs
    ) -> DetailedResponse

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 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'. Please make sure that the provided token has the required authority for the request.

Query Parameters

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

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

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

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

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

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

    Allowable values: [asc,desc]

    Default: asc

  • Defines if the entity history is included in the response

    Default: false

The ListServiceIds options.

The listServiceIds options.

parameters

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

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

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

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

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

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

    Allowable values: [asc,desc]

    Default: asc

  • Defines if the entity history is included in the response.

    Default: false

parameters

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

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

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

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

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

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

    Allowable values: [asc,desc]

    Default: asc

  • Defines if the entity history is included in the response.

    Default: false

  • curl -X GET 'https://iam.cloud.ibm.com/v1/serviceids?account_id=ACCOUNT_ID&name=My-serviceID' -H 'Authorization: Bearer TOKEN' -H 'Content-Type: application/json'
    
  • 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))
  • ListServiceIdsOptions listServiceIdsOptions = new ListServiceIdsOptions.Builder()
        .accountId(accountId)
        .name(serviceIdName)
        .build();
    
    Response<ServiceIdList> response = service.listServiceIds(listServiceIdsOptions).execute();
    ServiceIdList serviceIdList = response.getResult();
    System.out.println(serviceIdList.toString());
  • const params = {
      accountId: accountId,
      name: serviceIdName,
    };
    
    iamIdentityService.listServiceIds(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err);
      });
  • 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 format for the list service ID V1 REST request

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

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

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