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
Request URL
https://<BMC Helix Portal URL>/ims/api/v1/access_keysRequest URL with optional parameters
https://<BMC Helix Portal URL>/ims/api/v1/access_keys?page={pagenumber}&size={records}&orderBy=created_date_time&sortOrder=ascRequest 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:
| no | string |
| sortOrder | query | Sort order of the details to be retrieved. Valid values:
| 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/{id}
Request URL
https://<BMC Helix Portal URL>/ims/api/v1/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 |
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
Request URL
https://<BMC Helix Portal URL>/ims/api/v1/access_keysRequest 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:
Note: The input values are case sensitive. | yes | string |
| expiry_time | body | Expiration date and time. This field applies only if you specify the Notes:
| 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/{id}
Request URL
https://<BMC Helix Portal URL>/ims/api/v1/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 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/{id}
Request URL
https://<BMC Helix Portal URL>/ims/api/v1/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: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 |
|---|---|---|---|---|
| id | 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:
Note: The input values are case sensitive. | no | string |
| expiry_time | body | Expiration date and time. This field applies only if you specify the Notes:
| 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:
| 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/{id}/access_secret_key
Request URL
https://<BMC Helix Portal URL>/ims/api/v1/access_keys/{id}/access_secret_keyRequest 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 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
Request URL
https://<BMC Helix Portal URL>/ims/api/v1/access_keys/searchRequest URL with optional parameters
https://<BMC Helix Portal URL>/ims/api/v1/access_keys/search?page={pageNumber}&size={records}&orderBy=created_date_time&sortOrder=ascRequest 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:
| no | string |
| sortOrder | query | Sort order of the details to be retrieved. Valid values:
| 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:
| 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
Request URL
https://<BMC Helix Portal URL>/ims/api/v1/users/{user_id}/access_keysRequest 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=ascRequest 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:
| no | string |
| sortOrder | query | Sort order of the details to be retrieved. Valid values:
| 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}
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
Request URL
https://<BMC Helix Portal URL>/ims/api/v1/users/{user_id}/access_keysRequest 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:
Note: The input values are case sensitive. | yes | string |
| expiry_time | body | Expiration date and time. This field applies only if you specify the Notes:
| 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}
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}
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:
Note: The input values are case sensitive. | no | string |
| expiry_time | body | Expiration date and time. This field applies only if you specify the Notes:
| 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:
| 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
Request URL
https://<BMC Helix Portal URL>/ims/api/v1/users/{user_id}/access_keys/{id}/access_secret_keyRequest 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."
}
Comments
Log in or register to comment.