This documentation supports releases of BMC Helix Portal up to December 31, 2021. To view the latest version, select the version from the Product version menu.

Access and authentication for the REST API

Requests to all endpoints in the REST API must be on behalf of a BMC Helix Portal user. Before processing a request, the API authenticates the request to determine the user.

After successful authentication, a permission check decides if the user is allowed to perform the requested action. 

The process of authentication is based on various tokens that are obtained by running the endpoints described below.


Getting the JSON Web Token

To run an endpoint, you must first authenticate into the product by getting the JSON Web Token (JWT). The JWT is an access token that enables users to make authenticated calls to secured API endpoints. On every request, the token must be provided in the request as a header. The passed token informs the API that the bearer of the token has been authorized to both access the API and perform authorized actions defined in the user permissions. 

When you run the endpoint for getting the refresh token, in the response you get the initial JWT and the refresh token together. 

These tokens remain valid for a limited duration:

  • The refresh token expires after 24 hours.
  • The JWT expires after 15 minutes.

You can start running endpoints with the initial JWT received in the response. However, without the refresh token, authentication can be cumbersome for long running applications that need to make multiple requests. This is because after the JWT expires, the user gets logged out of the system and needs to log in again. As a result, after every 15 minutes, the application will need to get the initial JWT by providing the required credentials. 

Therefore, we recommend that you use the following two-step process:

  1. Get the refresh token
  2. Get the JWT using the refresh token received in the earlier step.

The application can use the refresh token (stored in a variable) to make the second call to get the JWT until the refresh token expires, after which the refresh token must be renewed. 

Security considerations

Protect the refresh token and the JWT as securely as a password. If any of these tokens get leaked before the expiry time, prevent unauthorized access by disabling the tenant-level or user-level access key.

Getting the refresh token

The refresh token enables you to reauthenticate without the need for manual user intervention. 

In the refresh token endpoint response, you receive:

  • token: Represents the refresh token
  • json_web_token: Represents the JWT

To obtain the refresh token, run the following endpoint:

POST /ims/api/v1/access_keys/login
Refresh token endpoint details
Request URL
 https://<BMC Helix Portal URL>/ims/api/v1/access_keys/login
Request body
{
 "access_key": "string",
 "access_secret_key": "string"
}
Example request body
{
 "access_key": "asdfaASDFADFD",
 "access_secret_key": "desfADFRgsdgdfgFDFSDFGfFDFghukkn"
}
Parameters


Successful response
{
   "user_id": "593825358753198",
   "principal_id": "YGT2OKHV3JPUSLTMFIOPVU7FSJUW44",
   "tenant_id": "804620852",
   "tenant_name": "ExtendTrial",
   "token": "eyJraWQiOiJkMTQyODMxZS1iMDZlLTQwYjctYjA5NS0xZjQ3MTg0MmE1YWUiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9.eyJzdWIiOiI4MDQ2MjA4NTI6OjU5MzgyNTM1ODc1MzE5OCIsImF1ZCI6ImJtY19hZGVfY2xvdWRfc2VydmljZXMiLCJhbXIiOlsiZXlKMWMyVnlYMmxrSWpvaU5Ua3pPREkxTXpVNE56VXpNVGs0SWl3aVlXTmpaWE56WDJ0bGVTSTZJbGxIVkRKUFMwaFdNMHBRVlZOTVZFMUdTVTlRVmxVM1JsTktWVmMwTkNJc0luUjVjR1VpT2lKQlVFa2lMQ0owWlc1aGJuUmZhV1FpT2lJNE1EUTJNakE0TlRJaWZRPT0iXSwiaXNzIjoiYm1jX2FkZV9jbG91ZF9zZXJ2aWNlc19pbXMiLCJ0eXBlIjoiUkVGX1RPS0VOIiwiZXhwIjoxNjA4ODk3Njc0LCJpYXQiOjE2MDg4MTEyNzQsImp0aSI6Ijc1ODVlOWYwLTU5OWItNGU5Yy1hZGJjLWE4Y2Y2Mjc0OTI0YyJ9.Xkx61gER5N1KMTE7WVY_06MjbsZXTgBWN9W4wcut1znaDb0Pz11a_GQ_LCNULqZHlvTlbhJyf5H_PmVF7EEwoBoy76MowvBh9mfcv8Ab0HApNX4ajuytPF0Voa4opJl1WGJAI8on50GkDlpDb-4rD34cB3litKvHLCHrtUXK2cypH_1Nhi-49RhiGjZxmKW9XAdC5ZlEd4Oxr-3a9UmwRD2h695B632ZwfONxUsJmYrgLX-2axLddJeCZ89EitvVHCLW2RLUUYx2mpynArG1mZ7-mIZgah7h_-bMLN_VWENqe3XPlM9r3mNwDfT-g1nmrPkOz9y5BFVgcqjLTJi51A",
   "json_web_token": "eyJraWQiOiJkMTQyODMxZS1iMDZlLTQwYjctYjA5NS0xZjQ3MTg0MmE1YWUiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9.eyJzdWIiOiI4MDQ2MjA4NTI6OjU5MzgyNTM1ODc1MzE5OCIsImF1ZCI6ImJtY19hZGVfY2xvdWRfc2VydmljZXMiLCJhbXIiOlsiZXlKMWMyVnlYMmxrSWpvaU5Ua3pPREkxTXpVNE56VXpNVGs0SWl3aVlXTmpaWE56WDJ0bGVTSTZJbGxIVkRKUFMwaFdNMHBRVlZOTVZFMUdTVTlRVmxVM1JsTktWVmMwTkNJc0luQnlhVzVqYVhCaGJGOXBaQ0k2SWxsSFZESlBTMGhXTTBwUVZWTk1WRTFHU1U5UVZsVTNSbE5LVlZjME5DSXNJblZ6WlhKZmMzUmhkSFZ6SWpvaVJVNUJRa3hGSWl3aWRIbHdaU0k2SWtGUVNTSXNJblJsYm1GdWRGOXBaQ0k2SWpnd05EWXlNRGcxTWlJc0luSnZiR1Z6SWpwYklqVXlNVFUyTVRZd01EZ3lNalkzT1NKZExDSm5jbTkxY0hNaU9sdGRMQ0p3WlhKdGFYTnphVzl1Y3lJNld5SnBiWE11ZFhObGNuTXViVzlrYVdaNUlpd2lhVzF6TG5CbGNtMXBjM05wYjI1ekxtMXZaR2xtZVNJc0ltbHRjeTV5YjJ4bGN5NWtaV3hsZEdVaUxDSnBiWE11Y0dWeWJXbHpjMmx2Ym5NdWNtVmhaQ0lzSW1sdGN5NXdaWEp0YVhOemFXOXVjeTVrWld4bGRHVWlMQ0pwYlhNdWRYTmxjbk11YkdsemRDSXNJbWx0Y3k1MWMyVnljeTVrWld4bGRHVWlMQ0pwYlhNdWNtOXNaWE11Y21WaFpDSXNJbWx0Y3k1aFkyTmxjM05mYTJWNWN5NWtaV3hsZEdVaUxDSnBiWE11Y205c1pYTXViVzlrYVdaNUlpd2lhVzF6TG5KdmJHVnpMbU55WldGMFpTSXNJbWx0Y3k1MWMyVnljeTV5WldGa0lpd2lhVzF6TG5WelpYSnpMbU55WldGMFpTSXNJbWx0Y3k1d1pYSnRhWE56YVc5dWN5NXNhWE4wSWl3aWFXMXpMbkp2YkdWekxteHBjM1FpWFgwPSJdLCJpc3MiOiJibWNfYWRlX2Nsb3VkX3NlcnZpY2VzX2ltcyIsInR5cGUiOiJBQ0NFU1NfVE9LRU4iLCJleHAiOjE2MDg4MTIxNzQsImlhdCI6MTYwODgxMTI3NCwianRpIjoiMzdmOGZkODMtNzBhMC00NmVhLTgzNDUtM2I5NmJkNTA3YzRjIn0.K9nSXrXDOx3mYFJi2tUGDBzAoSHVxWD5FvCByIJY8BH_rRyi-_AowWKV31BYEP0IN3HhtMnH5SUlcnCK-5p8H_1HtY8aHKci6AUV63AsMk6y09SX7mAVs0VHf3LfdpxSyaTfWyj19AKQXuLTwyFZ8eaNiLbO2Rp9QbZwdolUMaZJcae-ue6DAops6mx0rP9Rq6xlimqNUXI-g3mnNKnnSk7VBgckWXFSBMpYwKl2wTMW4KE7KuiM1lfgxd_McObwHLRXa4nt4lo4cl5Ze8JDehklOOmO5am6kvoatBB6Bi-E3-SSMegTfu4bB6VbshjjPyhdfva-seAy6O0iIUxgNw"
}
Unsuccessful response
{
   "timestamp": "2020-10-07T12:56:29.154123Z",
   "code": 401,
   "message": "Unauthorized"
}


Getting the JWT using the refresh token

If an application needs to make multiple requests, it can get the refresh token (expiry: 24 hours) and use this token to get the JWT.

To obtain the JWT, run the following endpoint:

POST /ims/api/v1/auth/tokens
JWT endpoint details
Request URL
 https://<BMC Helix Portal URL>/ims/api/v1/auth/tokens
Request body
{
 "token": "string"
}
Example request body
{
 "token": "eyJpYXQiOjE2MDIwNzY1NzA4ODgsInNydiI6Imh0dHBzOi8vYXBpLWFknNwcy5zZWHMuYm1jLmNvbS9yc3NvIiwicmxtIjoiQ29vY2EuODI1ODY5MDAyIiwidG9rZW5JZCI6Il81ZGE1NGZlNS0zYWI3LTRiZGEtYmVhMi03ODU5MjY2MDgzZWMifQ=="
}
Parameters


Successful response
{
 "json_web_token": "eyJraWQiOiI5Mjc5MjA3Mi0xYjZlLTRjMDItYjQ3MC1mODYTY4MWMiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9.eyJzdU5NjM2ODU0NjEzMSIsImF1ZCI6ImJtY19hZGVfY2xvdWRfc2VydmljZXMiLCJhbXIiOlsiZXlKMWMyVnlYMmxrSWpvaU1qRTNOVGsyTXpZNE5UUTJNVE14SWl3aWNISnBibU5wY0dGc1gybGtJam9pYW1WbVprUWlMQ0oxYzJWeVgzTjBZWFIxY3lJNklrVk9RVUpNUlNJc0luUjVjR1VpT2lKUVJWSlRUMDRpTENKMFpXNWhiblJmYVdRaU9pSTRNalU0Tmprd01ESWlMQ0p5YjJ4bGN5STZXeUl6TnpZd056WXpPREUzTmpJMU5qSWlMQ0l5TlRNNU9EQXlOek01T1RjeU1Ea2lMQ0k0T1RNeU1EWXdNVE15TXpZME9Ea2lYU3dpWjNKdmRYQnpJanBiSWpNMk1UWTFOalkzT1RBeU9EYzRNeUpkTENKd1pYSnRhWE56YVc5dWN5STZXeUlxSWwxOSJdLCJpc3MiOiJibWNfYWRlX2Nsb3VkX3NlcnZpY2VzX2ltcyIsInR5cGUiOiJBQ0NFU1NfVE9LRU4iLCJleHAiOjE2MDIwNzc1OTksImlhdCI6MTYwMjA3NjY5OSwianRpIjoiMjc4MjJiOTUtN2M2OC00ZjY1LWFlNTYtZWJmN2YyMmFhYmNjIn0.F0ZOHo2e4sHXep6iLDYfQHWV5J6hXw5B7bL-XEl0TduCk5Rwgq3WuZ3pb7S8KCReRpL34iL7LYbeNdtS9lb1KHQdaetzLhEDTLTnZWbdnDr3ps1xgly-kWef9d-OaDZLY1PtM823Np8P7nD39YjzjertojqdISiBaeJyrYrJDTYHpA-5wuE3X5OreXOABj-mcLdWoDEB47Hn0o93njmbe4Twhd1uWl6KetCM1y-7rhjS6QLwZG-Bw7sWJywomevv_3om1KJYPISgzuL2Txv19yNB8QUz_q-7qicfcLqpb0_bipVquOBkfkldug3hpRS6nGVNfig"
}
Unsuccessful response
{
   "timestamp": "2020-10-07T13:32:24.149148Z",
   "code": 401,
   "message": "Unauthorized",
   "error": "Unauthorized"
}


Failed authentication

A request to generate a token with incorrect credentials, or for a user that has been deactivated, results in a 401 Unauthorized HTTP status code.

A standard endpoint request that omits a valid, unexpired token also results in a 401 Unauthorized status code.

Permissions

After successful authentication of a user, the endpoints check if the user has the permission to perform the requested action. Users require the same permissions as they would for attempting the action through the equivalent user interface. If the user lacks the required permission, a 403 Forbidden status code is returned from the endpoint.