Access key endpoints in the REST API


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

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


Access keys

You can perform the following operations related to access keys: 

GET /ims/api/v1/access_keys
Get all access keys
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&userType=api
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Parameters
Successful response
{
"records": [{
"user_id": "692632783239339",
"name": "sample access key",
"type": "TENANT",
"access_key": "PYZ24AOA4KVO5B26M7YEU26BVABWT0",
"status": "ACTIVE",
   "non_deletable": false,
   "created_date": "2022-03-03T10:24:17.187793",
"expiry_enum": "Never expires (not recommended)",
"key_expired": false
},

{
         "user_id": "442681916544590",
         "name": "00aTKeycynwjycmxv",
         "type": "API",
         "description": "This is a testing API key",
         "access_key": "V9TCLAHQJSE30YXK4R84GAN2RMMW39",
         "status": "ACTIVE",
         "created_date": "2022-07-01T18:39:56.793250",
         "expiry_enum": "Never expires (not recommended)",
         "key_expired": false,
        "non_deletable": true,
         "rotation":          {
            "rotation_period": 25,
            "grace_period": 10,
            "last_rotation_date": "2022-07-01T18:39:56.478202",
            "next_rotation_date": "2022-07-26T18:39:56.478205",
            "old_rotation_key": "FFFY2YXI2DG2WLMYB8679TRFN8NRZW",
            "never_rotate": false
         }
     },
 {
"user_id": "635270014775600",
"name": "Rotation Key",
"type": "API",
"description": "rotation key",
"access_key": "AVLGMV11CDZ8HYL5EN4J7K9MTEEY1D",
"last_access": "2022-05-16T10:27:20.936711",
"expiry_time": "Never expires (not recommended)",
"status": "ACTIVE",
   "non_deletable": true,  
   "created_date": "2022-05-16T10:27:20.936711",
"expiry_enum": "Never expires (not recommended)",
"key_expired": false,
"rotation": {
"rotation_period": 30,
"grace_period": 7,
"last_rotation_date": "2022-05-16T10:27:20.746428",
"next_rotation_date": "2022-06-15T10:27:20.746430",
"old_rotation_key": "V0P0MUBYU5JWO3DX593S681YVIEK2L"
}
}
  ],
               "_metadata": {
               "page": 0,
               "records_per_page": 1000,
               "page_count": 0,
               "total_count": 10
              }
}  
                                
GET /ims/api/v1/access_keys/{access_key}
Get details of a specific 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
Successful response

For an API key:

{
 "user_id": "635270014775600",
  "name": "RotationKeyaM4Ub",
  "type": "API",
  "description": "rotation key",
  "access_key": "AVLGMV11CDZ8HYL5EN4J7K9MTEEY1D",
  "access_secret_key": "IK9zknQvJUa9bUxptiliWwCERQnxfP7THiszv0KMpVC3j8QxT1",
  "status": "ACTIVE",
  "created_date": "2022-05-16T10:27:20.936711",
  "expiry_enum": "Never expires (not recommended)",
  "key_expired": false,
  "non_deletable": false,    
  "rotation": {
                "rotation_period": 30,
                "grace_period": 7,
                "last_rotation_date": "2022-05-16T10:27:20.746428",
                "next_rotation_date": "2022-06-15T10:27:20.746430",
                "old_rotation_key": "V0P0MUBYU5JWO3DX593S681YVIEK2L",
                "never_rotate": false                
 }
}

For an access key:  

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


Unsuccessful response

For an access key:

{
 "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 access key for a tenant
Request URL
https://<BMC Helix Portal URL>/ims/api/v1/access_keys
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Example Request body

To create an access key:

{
 "name": "RotationKeyyptdo",
 "type": "TENANT",
 "description": "rotation key",
 "expiry_enum": "30 days"
 }


To create an API key:

{
 "name": "RotationKeyUfQT6",
 "type": "API",
 "description": "rotation key",
 "expiry_enum": "string",
 "non_deletable": true,
  "expiry_time": "2020-12-16T11:54:42.453Z",
  "rotation":{
             "rotation_period": "30",
             "grace_period": "7"
             "never_rotate": false
            }
}
Parameters
Successful response

For access key:

{
  "user_id": "486063029087255",
  "name": "Accesskey",
  "access_key": "NN77PVFKOYF8OULA9SRDI1K46PYSXP",
  "access_secret_key": "FTu020KjSCGokjFGYjuTN9Eeyn6kh9uJ6dnuSTOG2XISCV7FL2",
  "expiry_time": "2022-08-07T23:59:59",
  "key_expired": false,
  "non_deletable": false,    
  "status": "ACTIVE",
  "expiry_enum": "30 days",
  "description": "Key for user access"
}


For API key:

{
  "user_id": "542210042784826",
  "name": "RotationKeyqnRP2",
  "access_key": "40GL8YTH6961DGINPSUO79B42U0F4T",
  "access_secret_key": "bsjBEhGK4CgBElvPdIoDcI9ahD3KeYbpzcpXTBsdr0mMfUzJBy",
  "key_expired": false,
  "non_deletable": true,
   "status": "ACTIVE",
  "expiry_enum": "Never expires (not recommended)",
  "description": "rotation key",
  "rotation":    {
     "rotation_period": 30,
     "grace_period": 7,
     "next_rotation_date": "2022-06-22T09:03:54.462769"
  }
}
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 an 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
Successful response
{
 "message": "SUCCESS"
}
Unsuccessful response

Scenario 1: When the access key does not exist.

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

Scenario 2: When the user is attempting to delete an API key that is disabled for deletion.

{  
 "timestamp": "2022-10-06T09:19:31.553582Z",
 "code": 1800,
 "message": "Operation not allowed.",
 "error": "You cannot delete API key JPQ65JON9LVD6RX6WC0WQJAMULKZ1F because it is disabled for deletion." } }
PATCH /ims/api/v1/access_keys/{access_key} 
Update an 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

For Access key:

{     

"name": "Access key",
 "type": "API",
 "description": "access key",  
 "non_deletable": false,
 "expiry_enum": "string",
 
}
Example request body

For API key:

{
 "name": "RotationKeyUfQT6",
 "type": "API",
 "description": "rotation key",
 "rotation":{
 "rotation_period": "30",
 "non_deletable": true,
 "grace_period": "7"
 "never_rotate": false
}
}

Parameters

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

Successful response
{
  "user_id": "675602116861709",
  "name": "RotationKeyUfQT6",
  "access_key": "PAMNO5EHF3FON37PQ4DF7EFGR1NER8",
  "access_secret_key": "IK9zknQvJUa9bUxptiliWwCERQnxfP7THiszv0KMpVC3j8QxT1",
  "key_expired": false,
  "status": "ACTIVE",
  "expiry_enum": "Never expires (not recommended)",
  "description": "rotation key",
  "rotation":    {
     "rotation_period": 30,
     "key_grace_period": 7,
     "next_rotation_date": "2022-06-17T08:48:32.066502"
  }
}
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 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
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
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",
     "non_deletable": true,
      "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"
}

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

Manually regenerate an API key
Request URL
https://<BMC Helix Portal URL>/ims/api/v1/rotate_now/{access_keys}
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Parameter

Name

Located in

Description

Mandatory

Scheme

access keys

path

Access key for which you want to retrieve details.

yes

string

Successful response for API key
{
  "user_id": "801919373583006",
  "name": "RotationKeyCnYWi",
  "access_key": "KYWBYDC8K5IACBEU1GXH467Z9LKTCD",
  "access_secret_key": "CMkELVuZVu4Gs02yTT5PMD5aM6cpWbvkcHzcZSFxXZHkrBIc6K",
  "key_expired": false,
  "status": "ACTIVE",
  "expiry_enum": "Never expires (not recommended)",
  "non_deletable": true,
  "description": "rotation key",
  "rotation":    {
     "rotation_period": 30,
     "grace_period": 7,
     "last_rotation_date": "2022-07-08T07:41:26.430509",
     "next_rotation_date": "2022-08-07T07:41:26.430514",
     "old_rotation_key": "GDOA8XYSXJW729TU0Z6YWO01GHR4ZS",
     "never_rotate": false
  }
}

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


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
POST /ims/api/v1/users/{user_id}/access_keys/{id}access_secret_key
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Parameters
Successful response
Unsuccessful response
PATCH /ims/api/v1/access_keys/rotate_now/{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
{{
 "user_id": "string",
 "name": "string",
 "access_key": "string",
 "access_secret_key": "string",
 "type": "string",
 "last_access": "string",
 "expiry_time": "string",
 "key_expired": true,
 "status": "string",
 "created_date": "string",
 "expiry_enum": "string",
 "description": "string",
 "rotation": {}
} }
Example request body
{
}

Parameters

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

Successful response
{
 
}
Unsuccessful response
{
 
}

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*