Authentication and permissions in the TSWS REST API

Requests to all endpoints in the REST API are executed on behalf of a TrueSight Presentation Server user. Before processing a request, the API authenticates the user in Atrium Single Sign-On and the user's authorization profile determines whether the user has permission to execute the task.

If authentication is successful, an authentication token is created and sent to the Web Service client. The token is used in subsequent API calls to the TrueSight Presentation Server. By default, the authentication token is valid up to 24 hours.

Authentication tokens

Every HTTP request to the API must contain an "Authorization" header with the value "authToken <your_token>". For example:

curl -X POST "https://tsps.host.com:443/tsws/10.0/api/authenticate/login?username=admin&password=admin12345&tenantName=*" -H "accept: application/json"

An API token is an opaque string. A token is associated with one TrueSight Presentation Server user, and each token contains an expiry time, after which it is no longer valid, You should protect the token as securely as a password.

To generate an expiring token from the /login endpoint

To generate an expiring token for a TrueSight Presentation Server user, use the /api/authenticate/login endpoint. This endpoint accepts a POST request that contains the username, password, and tenant of the user.

As defined in the HTTP Basic authentication scheme defined in RFC 2617, you supply the three request parameters, as in the following example:

curl -X POST "https://tsps.host.com:443/tsws/10.0/api/authenticate/login?username=admin&password=admin12345&tenantName=*" -H "accept: application/json"

This sample request returns a response similar to the following example:

{
"authToken": "_ce14bc5c-e517-4df4-916f-5b942ec25b35",
"authPassed": true,
"expires": "2018-01-18T13:08:18.000Z",
"status": "OK"
}

All tokens generated from this endpoint request expire after one hour. Therefore this approach is more suited to a program or script which is run on-demand and on behalf of different users. Further tokens can be requested for a user as required.

Security considerations

Protect the API token as securely as a password. If the token is leaked before the expiry time, prevent unauthorized access by blocking REST API access for the remainder of the token's lifetime. You can do this in one of the following ways:

Remove the api-access permission from the user temporarily (see below).
Deactivate the user temporarily.

Alternatively, you can delete the user to invalidate all permanent and expiring tokens for them.

Note that, as with the user interface approach, it is not possible to generate a token for the local System user.

Failed authentication

A request to generate a token from /api/authenticate/login 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, endpoints check the user has permission to perform the requested action. Users require the same permissions as if they were attempting the action through the equivalent user interface or command line tool.

If writing a script or program to make unattended calls against the REST API, BMC recommends that you create a new local TrueSight Presentation Server user of type "API Access" for this purpose. This user can be granted the required permissions for the API, and a permanent token can be generated and embedded in the program.