Access and authentication for the REST API
Requests to all endpoints in the REST API must be on behalf of a BMC Helix Business Workflows user. Before processing a request, the API authenticates the request to determine the user. The API uses the OAuth 2.0 protocol for this authentication, and the process is based on tokens as described in the following sections.
After successful authentication, a permission check decides if the user is allowed to perform the requested action. This check uses the existing application permissions.
Authentication scheme
The BMC Helix Business Workflows REST API leverages the authentication mechanism of BMC Helix Innovation Suite.
BMC Helix Innovation Suite follows the OAuth 2.0 specification with API tokens provided by BMC Helix Single Sign-On. An authentication token is an opaque string. A token is associated with BMC Helix Business Workflows user, which could be either a local user or an LDAP user.
For more information about the authentication mechanism and how you can use BMC Helix Single Sign-On for authentication, see Using authorization REST APIs to consume BMC Helix Single Sign-On
Authentication and authorization
Perform the following steps to generate an OAuth2.0 Access Token. This token serves as your gateway for authentication and authorization, enabling secure access to the extensive BMC Helix Business Workflows API ecosystem.
To generate an access token
- Generate API authentication token using the authorization API: POST /api/rx/authentication/loginrequest
- Provide your login ID and password in this authorization API.
- Copy the access token from the response and use it to authorize API requests while accessing any API endpoints.
Parameters
Name | Required/Optional | Description | Type | Example | Notes |
|---|---|---|---|---|---|
id | Required | Remedy Server user login account | String | hannah_admin | Locate this parameter in the request body. This parameter is not specified by default. |
password | Required | Password | String | <your_password> | Locate this parameter in the request body. This parameter is not specified by default. |
Example request body
{
"userName": "<your_user>",
"password": "<your_password>"
}
Response
Response | Value | Notes |
|---|---|---|
HTTP code | 200 | Application returns an authentication token that is valid for about half an hour. |
| HTTP code | 400 | User not found |
Permissions
During authentication, a permission check decides whether the user is allowed to perform the requested action. The user must have the required permission in BMC Helix Business Workflows to perform the operation.