Access key endpoints in the REST API

The following section provides a list of supported endpoints for tenant-level and user-level access keys and details about running these endpoints. For more information about tenant-level and user-level access keys and how they can be used, see User access.

Before you run an endpoint, you must authenticate yourself. For more information, see Access and authentication for the REST API.

Tenant-level access keys

You can perform the following operations related to tenant-level access keys:

GET `/ims/api/v1/access_keys`

Get all access keys under a tenant

Request URL

https://<BMC Helix Portal URL>/ims/api/v1/access_keys

Request URL with optional parameters

https://<BMC Helix Portal URL>/ims/api/v1/access_keys?page={pagenumber}&size={records}&orderBy=created_date_time&sortOrder=asc

Request header

Content-Type: application/json
Authorization: Bearer <JWT_token>

Parameters

Name	Located in	Description	Mandatory	Schema
page	query	Page number from which you want to retrieve access keys. Note that the page number starts from 0 (default). Use this parameter in conjunction with the size parameter.	no	integer
size	query	Total number of records that you want to retrieve from a page. Default: 1000 records	no	integer
orderBy	query	Column on which you want to sort. Valid values: `user_id` `name` `description` `access_key` `status` `expiry_enum` (Default) `created_date_time`	no	string
sortOrder	query	Sort order of the details to be retrieved. Valid values: (Default) `asc` `desc`	no	string

Successful response

{
  "records": [
    {
      "user_id": "258024377281729",
      "name": "Sample tenant accesskey",
      "description": "tenant accesskey",
      "access_key": "K0R2XUH8CNTK5U2S4XB6OATH8BWOGR",
      "expiry_time": "2020-11-22T23:59:59",
      "status": "ACTIVE",
      "created_date": "2020-10-23T16:28:55.392754",
      "expiry_enum": "30 days",
      "key_expired": true
    },
    {
      "user_id": "369501394581102",
      "name": "ITSM_WEBHOOK_IMS_KEY",
      "description": "IMS access key for ITSM user sync",
      "access_key": "AQMJKO7CQ043563ALSIGILJS9RD66Q",
      "status": "ACTIVE",
      "created_date": "2020-12-18T06:43:20.419861",
      "expiry_enum": "Never expires (not recommended)",
      "key_expired": false
    }
  ],
  "_metadata": {
    "page": 0,
    "records_per_page": 1000,
    "page_count": 1,
    "total_count": 2
  }
}

Unsuccessful response

{
  "records": [],
  "_metadata": {
    "page": 0,
    "records_per_page": 1000,
    "page_count": 0,
    "total_count": 0
  }
}

GET `/ims/api/v1/access_keys/{`access_key}

Get details of a specific tenant-level access key

Request URL

https://<BMC Helix Portal URL>/ims/api/v1/access_keys/{access_key}

Request header

Content-Type: application/json
Authorization: Bearer <JWT_token>

Parameters

Name	Located in	Description	Mandatory	Schema
access key	path	ID of the access key for which you want to retrieve details.	yes	string

Successful response

{
  "user_id": "796608849380495",
  "access_key": "6M0EIUCU8CQU11W9R7D3LB9UKVEWOM",
  "name": "tenant access key",
  "expiry_time": "2020-10-15T23:59:59",
  "key_expired": true,
  "status": "ACTIVE",
  "created_date": "2020-10-13T17:46:03.102746",
  "expiry_enum": "Custom value"
}

Unsuccessful response

{
  "timestamp": "2020-12-19T10:28:44.713955Z",
  "code": 1700,
  "message": "Access key not found.",
  "error": "Access key with id 6M0EIUCU8CQU11W9R7D3LB9UKVEWOA not found."
}

POST `/ims/api/v1/access_keys`

Create a tenant-level access key

Request URL

https://<BMC Helix Portal URL>/ims/api/v1/access_keys

Request header

Content-Type: application/json
Authorization: Bearer <JWT_token>

Request body

{
  "description": "string",
  "expiry_enum": "string",
  "expiry_time": "2020-12-16T11:54:42.453Z",
  "name": "string"
}

Example Request body

{
  "description": "Tenant A access key",
  "expiry_enum": "30 days",
  "expiry_time": "2020-12-19T09:38:45.713Z",
  "name": "First tenant key"
}

Parameters

Name	Located in	Description	Mandatory	Schema
description	body	Description of the access key.	no	string
expiry_enum	body	Duration after which key expires. Valid values: (default) 60 days 30 days 90 days Custom value Never expires (not recommended) Note: The input values are case sensitive.	yes	string
expiry_time	body	Expiration date and time. This field applies only if you specify the `expiry_enum` parameter value as `Custom value`. Notes: You cannot set the current date as the expiry date. The expiry time format must be YYYY-MM-dd'T'HH:mm:ss.SSS'Z'. For example, 2020-09-01T14:59:55.711Z. However, when you apply the expiry time, only the date is considered. The time is ignored.	no	string
name	body	Name for the access key that you want to create.	yes	string

Successful response

{
  "user_id": "796392418645088",
  "name": "first tenant key",
  "access_key": "3QKJFJKHUSFHICN6FZRSJBZMN67Z5V",
  "access_secret_key": "cYud3vwtSo2CNgIzJI21QCDAQsqenAGtnNRDdsoCocfipvjbMI",
  "expiry_time": "2021-01-18T23:59:59",
  "key_expired": false,
  "status": "ACTIVE",
  "expiry_enum": "30 days"
}

Unsuccessful response

{
  "timestamp": "2020-12-16T12:18:49.392740Z",
  "code": 400,
  "message": "BAD_REQUEST",
  "error": "Invalid ExpiryEnum provided:: 60 DAYS"
}

DELETE `/ims/api/v1/access_keys/{access_key`}

Delete a tenant-level access key

Request URL

https://<BMC Helix Portal URL>/ims/api/v1/access_keys/{access_key}

Request header

Content-Type: application/json
Authorization: Bearer <JWT_token>

Parameters

Name	Located in	Description	Mandatory	Schema
access key	path	ID of the access key that you want to delete.	yes	string

Successful response

{ "message": "SUCCESS" }

Unsuccessful response

{
  "timestamp": "2020-12-19T10:48:40.051603Z",
  "code": 1700,
  "message": "Access key not found.",
  "error": "Access key with id 3QKJFJKHUSFHICN6FZRSJBZMN67Z5V not found."
}

PATCH `/ims/api/v1/access_keys/{access_key`}

Update a tenant-level access key

Request URL

https://<BMC Helix Portal URL>/ims/api/v1/access_keys/{access_key}

Request header

Content-Type: application/json
Authorization: Bearer <JWT_token>

Request body

{
  "description": "string",
  "expiry_enum": "string",
  "expiry_time": "2021-01-06T13:14:54.944Z",
  "name": "string",
  "status": "string"
}

Example request body

{
  "description": "Tenant access key",
  "expiry_enum": "30 days",
  "name": "first tenant Accesskey",
  "status": "ACTIVE"
}

Parameters

At a minimum, you need to provide any one of the nonmandatory parameters.

Name	Located in	Description	Mandatory	Schema
access_key	path	ID of the tenant-level access key that you want to update.	yes	string
description	body	Updated description for the access key.	no	string
expiry_enum	body	Duration after which key expires. Valid values: (default) 60 days 30 days 90 days Custom value Never expires (not recommended) Note: The input values are case sensitive.	no	string
expiry_time	body	Expiration date and time. This field applies only if you specify the `expiry_enum` parameter value as `Custom value`. Notes: You cannot set the current date as the expiry date. The expiry time format must be YYYY-MM-dd'T'HH:mm:ss.SSS'Z'. For example, 2020-09-01T14:59:55.711Z. However, when you apply the expiry time, only the date is considered. The time is ignored.	no	string
name	body	Updated name for the access key.	no	string
status	body	Status that you want to set for the access key: Valid values: ACTIVE INACTIVE	no	string

Successful response

{ "message": "SUCCESS" }

Unsuccessful response

{
  "timestamp": "2020-12-19T10:59:42.612972Z",
  "code": 400,
  "message": "BAD_REQUEST",
  "error": "Invalid ExpiryEnum provided:: 60 Days"
}

POST `/ims/api/v1/access_keys/{access_key`}/access_secret_key

Regenerate the secret access key for a specific tenant-level access key

Request URL

https://<BMC Helix Portal URL>/ims/api/v1/access_keys/{access_key}/access_secret_key

Request header

Content-Type: application/json
Authorization: Bearer <JWT_token>

Parameters

Name

Located in

Description

Mandatory

Schema

access key

path

ID of the access key for which you want to generate a new secret key.

Note: You can generate a new secret key only for those access keys that are active.

yes

string

Successful response

{
  "access_key": "25WGUCF93PP0NJ5U01T6SZCEGQS0O3",
  "access_secret_key": "3LMVdvGEdbRoZkJjeabrlIxSb8BclamBFh3wyCBysyKDNlwYqx",
  "key_expired": false
}

Unsuccessful response

{
   "timestamp": "2020-12-18T17:47:22.806267Z",
   "code": 1800,
   "message": "Operation not allowed.",
   "error": "You cannot generate a new secret key when the access key is inactive."
}

POST `/ims/api/v1/access_keys/search`

Search for access keys under a tenant

Request URL

https://<BMC Helix Portal URL>/ims/api/v1/access_keys/search

Request URL with optional parameters

https://<BMC Helix Portal URL>/ims/api/v1/access_keys/search?page={pageNumber}&size={records}&orderBy=created_date_time&sortOrder=asc

Request header

Content-Type: application/json
Authorization: Bearer <JWT_token>

Request body

{
  "filters": [
    {
      "field": "string",
      "values": [
        "string"
      ]
    }
  ]
}

Example request body

{
  "filters": [
    {
      "field": "*",
      "values": [
        "tenant"
    ]
    }
  ]
}

Parameters

Name	Located in	Description	Mandatory	Schema
page	query	Page number from which you want to retrieve access keys. Note that the page number starts from 0 (default). Use this parameter in conjunction with the size parameter.	no	integer
size	query	Total number of records that you want to retrieve from a page. Default: 1000 records	no	integer
orderBy	query	Column on which you want to sort. Valid values: `user_id` `name` `description` `access_key` `status` `expiry_enum` (Default) `created_date_time`	no	string
sortOrder	query	Sort order of the details to be retrieved. Valid values: (Default) `asc` `desc`	no	string
field	body	Field by which you want to search access keys. At one time, you can search by the access key, access key name, or the description. If you want to perform a global search in all the fields, provide an asterisk () as the value. Valid values: `name` `description` `access_key`	Yes	string
values	body	Value with which you want to search the access keys. You can pass a comma-separated list of multiple values for all the valid fields except when you use an asterisk (*) as the field.	Yes	Array[string]

Successful response

{
   "records": [   {
      "user_id": "611240414166460",
      "name": "Tenant",
      "description": "AccessKey For Tenant",
      "access_key": "5L6IR092QVMI1XNH04K1NPMEDP8G4P",
      "last_access": "2020-12-31T19:43:44.823390",
      "expiry_time": "2021-01-02T23:59:59",
      "status": "ACTIVE",
      "created_date": "2020-12-31T19:43:41.906192",
      "expiry_enum": "Custom value",
      "key_expired": false
   }],
   "_metadata":    {
      "page": 0,
      "records_per_page": 1000,
      "page_count": 1,
      "total_count": 1
   }
}

Unsuccessful response

Scenario 1: If you search by passing the access key ID instead of the name or description.

{
   "records": [],
   "_metadata":    {
      "page": 0,
      "records_per_page": 1000,
      "page_count": 0,
      "total_count": 0
   }
}

Scenario 2: If you search by passing more than one value.

{
   "timestamp": "2020-12-31T19:43:11.060242Z",
   "code": 2300,
   "message": "BAD_REQUEST",
   "error": "Only one value for search is supported."
}

Scenario 3: If you search with any value other than "*" as the field parameter value.

{
   "timestamp": "2020-12-31T19:43:57.375969Z",
   "code": 2300,
   "message": "BAD_REQUEST",
   "error": "Unsupported search field: tenant_AK"
}

User-level access keys

You can perform the following operations related to user-level access keys:

GET `/ims/api/v1/users/{user_id}/access_keys`

Get all access keys for a user

Request URL

https://<BMC Helix Portal URL>/ims/api/v1/users/{user_id}/access_keys

Request URL with optional parameters

https://<BMC Helix Portal URL>/ims/api/v1/users/{user_id}/access_keys?page={pagenumber}&size={records}&orderBy=created_date_time&sortOrder=asc

Request header

Content-Type: application/json
Authorization: Bearer <JWT_token>

Parameters

Name	Located in	Description	Mandatory	Schema
user_id	path	ID of the user whose access key information you want to retrieve.	yes	string
page	query	Page number from which you want to retrieve access keys. Note that the page number starts from 0 (default). Use this parameter in conjunction with the size parameter.	no	integer
size	query	Total number of records that you want to retrieve from a page. Default: 1000 records	no	integer
orderBy	query	Column on which you want to sort. Valid values: `user_id` `name` `description` `access_key` `status` `expiry_enum` (Default) `created_date_time`	no	string
sortOrder	query	Sort order of the details to be retrieved. Valid values: (Default) `asc` `desc`	no	string

Successful response

{
  "records": [
    {
      "user_id": "549720570762485",
      "name": "user accesskey1",
      "access_key": "5DVQHB76PC0NHPO97DJGPA04J0QWQX",
      "expiry_time": "2020-10-18T23:59:59",
      "status": "ACTIVE",
      "created_date": "2020-10-16T11:09:38.928216",
      "expiry_enum": "Custom value",
      "key_expired": true
    },
    {
      "user_id": "549720570762485",
      "name": "user accesskey2",
      "access_key": "5OFXVAQD6OXXT555B6FLXE57VVNERO",
      "expiry_time": "2020-11-24T23:59:59",
      "status": "ACTIVE",
      "created_date": "2020-11-23T05:21:42.186514",
      "expiry_enum": "Custom value",
      "key_expired": true
    }
  ],
  "_metadata": {
    "page": 0,
    "records_per_page": 1000,
    "page_count": 1,
    "total_count": 2
  }
}

Unsuccessful response

{
  "timestamp": "2021-02-16T14:28:52.094135Z",
  "code": 1100,
  "message": "User not found.",
  "error": "Failed to find user by id [481388568570813]"
}

GET `/ims/api/v1/users/{user_id}/access_keys/{id}`

Get details of a specific user-level access key

Request URL

https://<BMC Helix Portal URL>/ims/api/v1/users/{user_id}/access_keys/{id}

Request header

Content-Type: application/json
Authorization: Bearer <JWT_token>

Parameters

Name	Located in	Description	Mandatory	Schema
id	path	ID of the access key for which you want to retrieve details.	yes	string
user_id	path	ID of the user whose access key information you want to retrieve.	yes	string

Successful response

{
  "user_id": "549720570762485",
  "access_key": "5DVQHB76PC0NHPO97DJGPA04J0QWQX",
  "name": "user accesskey1",
  "expiry_time": "2020-10-18T23:59:59",
  "key_expired": true,
  "status": "ACTIVE",
  "created_date": "2020-10-16T11:09:38.928216",
  "expiry_enum": "Custom value"
}

Unsuccessful response

{
  "timestamp": "2020-12-16T11:51:05.626556Z",
  "code": 1700,
  "message": "Access key not found.",
  "error": "Access key ID 5DVQHB76PC0NHPO97DJGPA04J0QWQZ could not be found under the user ID 549720570762485. Verify that the access key specified is correct."
}

POST `/ims/api/v1/users/{user_id}/access_keys`

Create a user-level access key (maximum key count is 2)

Request URL

https://<BMC Helix Portal URL>/ims/api/v1/users/{user_id}/access_keys

Request header

Content-Type: application/json
Authorization: Bearer <JWT_token>

Request body

{
  "description": "string",
  "expiry_enum": "string",
  "expiry_time": "2020-12-16T11:54:42.453Z",
  "name": "string"
}

Example request body

{
  "description": "accesskey2",
  "expiry_enum": "30 days",
  "name": "accesskey2"
}

Parameters

Name	Located in	Description	Mandatory	Schema
user_id	path	ID of the user for which you want to create the access key.	yes	string
description	body	Description of the access key.	no	string
expiry_enum	body	Duration after which key expires. Valid values: (default) 60 days 30 days 90 days Custom value Never expires (not recommended) Note: The input values are case sensitive.	yes	string
expiry_time	body	Expiration date and time. This field applies only if you specify the `expiry_enum` parameter value as `Custom value`. Notes: You cannot set the current date as the expiry date. The expiry time format must be YYYY-MM-dd'T'HH:mm:ss.SSS'Z'. For example, 2020-09-01T14:59:55.711Z. However, when you apply the expiry time, only the date is considered. The time is ignored.	no	string
name	body	Name of the access key.	yes	string

Successful response

{
  "user_id": "549720570762485",
  "name": "accesskey2",
  "access_key": "R4KKZ0PIIR0V39ZH8LKTZ88USMH0IJ",
  "access_secret_key": "UXorqKSihWrahxW2XX7dENHAV2FS4HfUFR5EtQZPNzu0Agdcp3",
  "expiry_time": "2021-01-15T23:59:59",
  "key_expired": false,
  "status": "ACTIVE",
  "expiry_enum": "30 days"
}

Unsuccessful response

Scenario 1: Invalid expiry_enum value.

{
  "timestamp": "2020-12-16T12:18:49.392740Z",
  "code": 400,
  "message": "BAD_REQUEST",
  "error": "Invalid ExpiryEnum provided:: 60 DAYS"
}

Scenario 2: If you try to create more than two user-level access keys.

{
   "timestamp": "2020-12-15T13:32:32.138939Z",
   "code": 500,
   "message": "INTERNAL_SERVER_ERROR",
   "error": "Key count exceeded. You can create a maximum of two keys only."
}

DELETE /ims/api/v1/users/{user_id}/access_keys/{id}

Delete a user-level access key

Request URL

https://<BMC Helix Portal URL>/ims/api/v1/users/{user_id}/access_keys/{id}

Request header

Content-Type: application/json
Authorization: Bearer <JWT_token>

Parameters

Name	Located in	Description	Mandatory	Schema
user_id	path	ID of the user whose access key information you want to retrieve.	yes	string
id	path	ID of the access key for which you want to retrieve details.	yes	string

Successful response

{ "message": "SUCCESS" }

Unsuccessful response

{
  "timestamp": "2020-12-16T15:05:01.440779Z",
  "code": 1700,
  "message": "Access key not found.",
  "error": "Access key ID R4KKZ0PIIR0V39ZH8LKTZ88USMH0IJ could not be found under the user ID 549720570762485. Verify that the access key specified is correct."
}

PATCH `/ims/api/v1/users/{user_id}/access_keys/{id}`

Update a user-level access key

Request URL

https://<BMC Helix Portal URL>/ims/api/v1/users/{user_id}/access_keys/{id}

Request header

Content-Type: application/json
Authorization: Bearer <JWT_token>

Request body

{
  "description": "string",
  "expiry_enum": "string",
  "expiry_time": "2021-01-06T13:14:55.414Z",
  "name": "string",
  "status": "string"
}

Example request body

{
  "description": "accesskey2",
  "expiry_enum": "30 days",
  "name": "accesskey2",
  "status": "ACTIVE"
}

Parameters

At a minimum, you need to provide any one of the non-mandatory parameters.

Name	Located in	Description	Mandatory	Schema
user_id	path	ID of the user whose access key information you want to update.
id	path	ID of the user-level access key that you want to update.	yes	string
description	body	Updated description for the access key.	no	string
expiry_enum	body	Duration after which key expires. Valid values: (default) 60 days 30 days 90 days Custom value Never expires (not recommended) Note: The input values are case sensitive.	no	string
expiry_time	body	Expiration date and time. This field applies only if you specify the `expiry_enum` parameter value as `Custom value`. Notes: You cannot set the current date as the expiry date. The expiry time format must be YYYY-MM-dd'T'HH:mm:ss.SSS'Z'. For example, 2020-09-01T14:59:55.711Z. However, when you apply the expiry time, only the date is considered. The time is ignored.	no	string
name	body	Updated name for the access key.	no	string
status	body	Status that you want to set for the access key: Valid values: ACTIVE INACTIVE	no	string

Successful response

{ "message": "SUCCESS" }

Unsuccessful response

{
  "timestamp": "2020-12-16T15:21:56.248741Z",
  "code": 1700,
  "message": "Access key not found.",
  "error": "Access key ID SELYK3OK99932UQV8Z14VHHMF4CU6Z could not be found under the user ID 549720570762485. Verify that the access key specified is correct."
}

POST/ims/api/v1/users/{user_id}/access_keys/{id}/access_secret_key

Regenerate secret access key for specific access key of a user

Request URL

https://<BMC Helix Portal URL>/ims/api/v1/users/{user_id}/access_keys/{id}/access_secret_key

Request header

Content-Type: application/json
Authorization: Bearer <JWT_token>

Parameters

Name

Located in

Description

Mandatory

Schema

user_id

path

ID of the user for whom you want to generate the secret key.

yes

string

id

path

ID of the access key (corresponding to the user ID) for which you want to generate the new secret key.

Note: You can generate a new secret key only for those access keys that are active.

yes

string

Successful response

{
  "access_key": "SELYK3OK99932UQV8Z14VHHMF4CU6J",
  "access_secret_key": "9ojnBiKwDQdA7QhnJNCd8ApMKRbjMBQqHvDZGgIRBX3Z4d1XCd",
  "key_expired": false
}

Unsuccessful response

{
  "timestamp": "2020-12-16T15:32:45.212071Z",
  "code": 1700,
  "message": "Access key not found.",
  "error": "Access key ID SELYK3OK99932UQV8Z14VHHMF4CU6Z could not be found under the user ID 549720570762485. Verify that the access key specified is correct."
}

Access key endpoints in the REST API

Tenant-level access keys

GET /ims/api/v1/access_keys

Request URL

Request URL with optional parameters

Request header

Parameters

Successful response

Unsuccessful response

GET /ims/api/v1/access_keys/{access_key}

Request URL

Request header

Parameters

Successful response

Unsuccessful response

POST /ims/api/v1/access_keys

Request URL

Request header

Request body

Example Request body

Parameters

Successful response

Unsuccessful response

DELETE /ims/api/v1/access_keys/{access_key}

Request URL

Request header

Parameters

Successful response

Unsuccessful response

PATCH /ims/api/v1/access_keys/{access_key}

Request URL

Request header

Request body

Example request body

Successful response

Unsuccessful response

POST /ims/api/v1/access_keys/{access_key}/access_secret_key

Request URL

Request header

Parameters

Successful response

Unsuccessful response

POST /ims/api/v1/access_keys/search

Request URL

Request URL with optional parameters

Request header

Request body

Example request body

Parameters

Successful response

Unsuccessful response

User-level access keys

GET /ims/api/v1/users/{user_id}/access_keys

Request URL

Request URL with optional parameters

Request header

Parameters

Successful response

Unsuccessful response

GET /ims/api/v1/users/{user_id}/access_keys/{id}

Request URL

Request header

Parameters

Successful response

Unsuccessful response

POST /ims/api/v1/users/{user_id}/access_keys

Request URL

Request header

Request body

Example request body

Parameters

Successful response

Unsuccessful response

DELETE /ims/api/v1/users/{user_id}/access_keys/{id}

Request URL

Request header

Parameters

Successful response

Unsuccessful response

PATCH /ims/api/v1/users/{user_id}/access_keys/{id}

GET `/ims/api/v1/access_keys`

GET `/ims/api/v1/access_keys/{`access_key}

POST `/ims/api/v1/access_keys`

DELETE `/ims/api/v1/access_keys/{access_key`}

PATCH `/ims/api/v1/access_keys/{access_key`}

POST `/ims/api/v1/access_keys/{access_key`}/access_secret_key

POST `/ims/api/v1/access_keys/search`

GET `/ims/api/v1/users/{user_id}/access_keys`

GET `/ims/api/v1/users/{user_id}/access_keys/{id}`

POST `/ims/api/v1/users/{user_id}/access_keys`

PATCH `/ims/api/v1/users/{user_id}/access_keys/{id}`