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 in the following sections:
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, the response includes 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 difficult for long-running applications that need to make multiple requests. This limitation 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:
- Get the refresh token
- Get the JWT by 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 the refresh token expires, it must be renewed.
WarningWarning
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.
To generate 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"
}
| Name | Located in | Description | Mandatory | Schema |
|---|
| access_key | body | | Yes | String |
| access_secret_key | body | Secret key corresponding to the access key. | Yes | String |
{
"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"
}
{
"timestamp": "2020-10-07T12:56:29.154123Z",
"code": 401,
"message": "Unauthorized"
}
To generate the JWT by using the refresh token
If an application needs to make multiple requests, it can obtain the refresh token, which expires in 24 hours, and use it to retrieve 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"
}
{
"token": "eyJpYXQiOjE2MDIwNzY1NzA4ODgsInNydiI6Imh0dHBzOi8vYXBpLWFknNwcy5zZWHMuYm1jLmNvbS9yc3NvIiwicmxtIjoiQ29vY2EuODI1ODY5MDAyIiwidG9rZW5JZCI6Il81ZGE1NGZlNS0zYWI3LTRiZGEtYmVhMi03ODU5MjY2MDgzZWMifQ=="
}
| Name | Located in | Description | Mandatory | Schema |
|---|
| token | body | Refresh token generated in the earlier step. | Yes | String |
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"
}
WarningThe access key (JWT token) must be associated with an administrator role or with a group or role that has permission to modify situation configurations.
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.
