Introduction

The IAM Identity Service API allows you to manage Service IDs and ApiKey identities as well as to create IAM access tokens for a user or Service ID.

curl -H "Accept: application/json" -H "Content-Type: application/x-www-form-urlencoded" -d  "grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=<...>" https://iam.cloud.ibm.com/identity/token"

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
}

In the event that an operation cannot be fulfilled, an appropriate 400 or 500 series HTTP response is returned from the server. The operations defined in the Reference section describe example errors that may be returned from a failed request. All responses from the Access Groups REST API will be in JSON format.

Below are potential error codes our API may 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 could not be found.
409 Conflict The entity is already in the requested state.
429 Too Many Requests Too many requests have been made within a given time window. Wait before calling the API again.
500 Internal error Error that is seen in an unexpected error situation.

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.

Additional headers

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

Transaction-Id

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 a serivce 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.

GET /v1/apikeys
Request

Custom Headers

  • Authorization Token used for the request. The supported token type is a Cloud IAM Access Token or UAA Bearer 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.

Response

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

No Sample Response

This method does not specify any sample responses.

Create an ApiKey

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
Request

Custom Headers

  • Authorization Token used for the request. The supported token type is a Cloud IAM Access Token or UAA Bearer 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

Response

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.

No Sample Response

This method does not specify any sample responses.

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.

GET /v1/apikeys/details
Request

Custom Headers

  • API key value.

  • Authorization Token used for the request. The supported token type is a Cloud IAM Access Token or UAA Bearer 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.

Response

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

No Sample Response

This method does not specify any sample responses.

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.

GET /v1/apikeys/{id}
Request

Custom Headers

  • Authorization Token used for the request. The supported token type is a Cloud IAM Access Token or UAA Bearer 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.

Response

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

No Sample Response

This method does not specify any sample responses.

Updates an ApiKey

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}
Request

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 or UAA Bearer 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

Response

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

No Sample Response

This method does not specify any sample responses.

Deletes an ApiKey

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}
Request

Custom Headers

  • Authorization Token used for the request. The supported token type is a Cloud IAM Access Token or UAA Bearer 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.

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.

POST /v1/apikeys/{id}/lock
Request

Custom Headers

  • Authorization Token used for the request. The supported token type is a Cloud IAM Access Token or UAA Bearer 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.

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.

DELETE /v1/apikeys/{id}/lock
Request

Custom Headers

  • Authorization Token used for the request. The supported token type is a Cloud IAM Access Token or UAA Bearer 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.

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.

GET /v1/serviceids/
Request

Custom Headers

  • Authorization Token used for the request. The supported token type is a Cloud IAM Access Token or UAA Bearer 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.

  • 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, createdAt and modifiedAt. If specified, the items are sorted by the value of this property

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

Response

Response body format for the list service ID V1 REST request

Status Code

  • Successful response. No further actions.

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

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

No Sample Response

This method does not specify any sample responses.

Create a service ID

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

POST /v1/serviceids/
Request

Custom Headers

  • Authorization Token used for the request. The supported token type is a Cloud IAM Access Token or UAA Bearer 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 service ID is locked for further write operations. False by default.

    Default: false

Request to create a service ID

Response

Response body format for service ID V1 REST requests

Status Code

  • successful operation

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

No Sample Response

This method does not specify any sample responses.

Get details of a service ID

Returns the details of a 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.

GET /v1/serviceids/{id}
Request

Custom Headers

  • Authorization Token used for the request. The supported token type is a Cloud IAM Access Token or UAA Bearer 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 service ID.

Response

Response body format for service ID V1 REST requests

Status Code

  • Successful response. No further actions.

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

  • service ID with provided ID not found.

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

No Sample Response

This method does not specify any sample responses.

Update service ID

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

PUT /v1/serviceids/{id}
Request

Custom Headers

  • 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 Token used for the request. The supported token type is a Cloud IAM Access Token or UAA Bearer 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 service ID to be updated.

Request to update a service ID

Response

Response body format for service ID V1 REST requests

Status Code

  • Successful - service ID updated

  • Parameter validation failed

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

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

  • Service ID with provided parameters not found

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

  • Internal Server error

No Sample Response

This method does not specify any sample responses.

Deletes a service ID and associated API keys

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

DELETE /v1/serviceids/{id}
Request

Custom Headers

  • Authorization Token used for the request. The supported token type is a Cloud IAM Access Token or UAA Bearer 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 service ID.

Response

Status Code

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

  • The service ID is locked

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

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

  • service ID with provided ID not found.

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

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

No Sample Response

This method does not specify any sample responses.

Lock the service ID

Locks a service ID 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.

POST /v1/serviceids/{id}/lock
Request

Custom Headers

  • Authorization Token used for the request. The supported token type is a Cloud IAM Access Token or UAA Bearer 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 service ID.

Response

Response body format for service ID V1 REST requests

Status Code

  • Successful locked

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

  • Service ID with provided uuid not found

  • Internal Server error

No Sample Response

This method does not specify any sample responses.

Unlock the service ID

Unlocks a service ID 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.

DELETE /v1/serviceids/{id}/lock
Request

Custom Headers

  • Authorization Token used for the request. The supported token type is a Cloud IAM Access Token or UAA Bearer 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 service ID.

Response

Response body format for service ID V1 REST requests

Status Code

  • Successful unlocked

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

  • Service ID with provided uuid not found

  • Internal Server error

No Sample Response

This method does not specify any sample responses.

Create an IAM access token for a user or service ID.

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

POST /v1/identity/token
Request

Form Parameters

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

  • The value of the api key used for grant type. For example: urn:ibm:params:oauth:grant-type:apikey

Response

Response body for POST /identity/token.

Status Code

  • successful operation

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

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

No Sample Response

This method does not specify any sample responses.