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>
Authorization: Bearer <JWT_token>
Parameters
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
}
}
"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
}
}
"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>
Authorization: Bearer <JWT_token>
Parameters
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"
}
"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."
}
"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>
Authorization: Bearer <JWT_token>
Request body
{
"description": "string",
"expiry_enum": "string",
"expiry_time": "2020-12-16T11:54:42.453Z",
"name": "string"
}
"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"
}
"description": "Tenant A access key",
"expiry_enum": "30 days",
"expiry_time": "2020-12-19T09:38:45.713Z",
"name": "First tenant key"
}
Parameters
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"
}
"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"
}
"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>
Authorization: Bearer <JWT_token>
Parameters
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."
}
"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>
Authorization: Bearer <JWT_token>
Request body
{
"description": "string",
"expiry_enum": "string",
"expiry_time": "2021-01-06T13:14:54.944Z",
"name": "string",
"status": "string"
}
"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"
}
"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.
Successful response
{ "message": "SUCCESS" }
Unsuccessful response
{
"timestamp": "2020-12-19T10:59:42.612972Z",
"code": 400,
"message": "BAD_REQUEST",
"error": "Invalid ExpiryEnum provided:: 60 Days"
}
"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>
Authorization: Bearer <JWT_token>
Parameters
Successful response
{
"access_key": "25WGUCF93PP0NJ5U01T6SZCEGQS0O3",
"access_secret_key": "3LMVdvGEdbRoZkJjeabrlIxSb8BclamBFh3wyCBysyKDNlwYqx",
"key_expired": false
}
"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."
}
"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>
Authorization: Bearer <JWT_token>
Request body
{
"filters": [
{
"field": "string",
"values": [
"string"
]
}
]
}
"filters": [
{
"field": "string",
"values": [
"string"
]
}
]
}
Example request body
{
"filters": [
{
"field": "*",
"values": [
"tenant"
]
}
]
}
"filters": [
{
"field": "*",
"values": [
"tenant"
]
}
]
}
Parameters
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
}
}
"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
}
}
"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."
}
"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"
}
"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>
Authorization: Bearer <JWT_token>
Parameters
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
}
}
"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]"
}
"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>
Authorization: Bearer <JWT_token>
Parameters
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"
}
"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."
}
"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>
Authorization: Bearer <JWT_token>
Request body
{
"description": "string",
"expiry_enum": "string",
"expiry_time": "2020-12-16T11:54:42.453Z",
"name": "string"
}
"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"
}
"description": "accesskey2",
"expiry_enum": "30 days",
"name": "accesskey2"
}
Parameters
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"
}
"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"
}
"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."
}
"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>
Authorization: Bearer <JWT_token>
Parameters
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."
}
"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>
Authorization: Bearer <JWT_token>
Request body
{
"description": "string",
"expiry_enum": "string",
"expiry_time": "2021-01-06T13:14:55.414Z",
"name": "string",
"status": "string"
}
"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"
}
"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.
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."
}
"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>
Authorization: Bearer <JWT_token>
Parameters
Successful response
{
"access_key": "SELYK3OK99932UQV8Z14VHHMF4CU6J",
"access_secret_key": "9ojnBiKwDQdA7QhnJNCd8ApMKRbjMBQqHvDZGgIRBX3Z4d1XCd",
"key_expired": false
}
"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."
}
"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."
}