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
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Parameters

NameLocated inDescriptionMandatorySchema
pagequery

Page number of the API Users page located under Common Services > User Management.

nointeger
sizequery

Total number of records that you want to retrieve from a page.

Default: 1000 records

no

integer
orderByquery

Sort order of the details to be retrieved.

Valid value: (Default) created_date_time

nostring

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}
 Get details of a specific tenant-level access key
Request URL
https://<BMC Helix Portal URL>/ims/api/v1/access_keys/{id}
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Parameters

NameLocated inDescriptionMandatorySchema
idpathID of the access key for which you want to retrieve details.
yesstring

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

NameLocated inDescriptionMandatorySchema
descriptionbodyDescription of the access key.nostring
expiry_enumbody

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.

yesstring
expiry_timebody

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.
nostring
namebodyName for the access key that you want to create.yesstring

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}
 Delete a tenant-level access key
Request URL
https://<BMC Helix Portal URL>/ims/api/v1/access_keys/{id}
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Parameters

NameLocated inDescriptionMandatorySchema
idpath

ID of the access key that you want to delete.

yesstring

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}
 Update a tenant-level access key
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.

NameLocated inDescriptionMandatorySchema
idpath

ID of the tenant-level access key that you want to update.

yesstring
descriptionbody

Updated description for the access key.

nostring
expiry_enumbody

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.

nostring
expiry_timebody

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.
nostring
namebodyUpdated name for the access key.nostring
statusbody

Status that you want to set for the access key:

Valid values:

  • ACTIVE
  • INACTIVE
nostring

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
 Regenerate the secret access key for a specific tenant-level access key
Request URL
https://<BMC Helix Portal URL>/ims/api/v1/access_keys/{id}/access_secret_key
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Parameters

NameLocated inDescriptionMandatorySchema
idpath

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.

yesstring

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

NameLocated inDescriptionMandatorySchema
pagequery

Page number of the API Users page from where you want to retrieve details.

This page is located on the console under Common Services > User Management.

nointeger
sizequery

Total number of records that you want to retrieve from a page.

Default: 1000 records

nointeger
orderByquery

Sort order of the details to be retrieved.

Valid value: (Default) created_date_time

nostring
fieldbody

Field by which you want to search access keys.

At one time, you can search either by the access key name or by the description. If you want to perform a global search in both the fields, provide asterisk (*) as the value.

Valid values:

  • name
  • description
Yesstring
valuesbody

Value with which you want to search the access keys.

At a time, you can provide only one value corresponding to the specified field.

YesArray[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
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Parameters

NameLocated inDescriptionMandatorySchema
user_idpath

ID of the user whose access key information you want to retrieve.

yesstring
pagequery

Page number of the API Key page located under the user icon displayed at the top right of the console.

nointeger
sizequery

Total number of records that you want to retrieve from a page.

Default: 1000 records

no

integer
orderByquery

Sort order of the details to be retrieved.

Valid value: (Default) created_date_time

nostring

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

NameLocated inDescriptionMandatorySchema
idpath

ID of the access key for which you want to retrieve details.

yesstring
user_idpath

ID of the user whose access key information you want to retrieve.

yesstring

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

NameLocated inDescriptionMandatorySchema
user_idpathID of the user for which you want to create the access key.yesstring
descriptionbodyDescription of the access key.nostring
expiry_enumbody

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.

yesstring
expiry_timebody

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.
nostring
namebodyName of the access key.yesstring

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

NameLocated inDescriptionMandatorySchema
user_idpath

ID of the user whose access key information you want to retrieve.

yesstring
idpath

ID of the access key for which you want to retrieve details.

yesstring

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.

NameLocated inDescriptionMandatorySchema
user_idpathID of the user whose access key information you want to update.

idpath

ID of the user-level access key that you want to update.

yesstring
descriptionbody

Updated description for the access key.

nostring
expiry_enumbody

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.

nostring
expiry_timebody

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.
nostring
namebodyUpdated name for the access key.nostring
statusbody

Status that you want to set for the access key:

Valid values:

  • ACTIVE
  • INACTIVE
nostring


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

NameLocated inDescriptionMandatorySchema
user_idpath

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

yesstring
idpath

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.

yesstring

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."
}


Was this page helpful? Yes No Submitting... Thank you

Comments