Authentication and permissions in the REST API

Requests to all endpoints in the REST API must be on behalf of a TrueSight Network Automation 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 this topic. After successful authentication, a rights check decides if the user is allowed to perform the requested action based on its associated roles. 

Authentication tokens

Following the OAuth 2.0 specification, every HTTPS request to the API must contain an "Authorization" header with the value "Bearer token". For example:

curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer 4747653682905491905' 'https://serverName:portNumber/bca-networks/apidocs/v1.0/groups?filter.realm=Default&orderBy=%2Bname&offset=1&limit=25'

 A token is associated with one TrueSight Network Automation user who must be granted the right to login using web services. Tokens contain an expiry time, after which they are no longer valid. You must protect a token as securely as a password.

You can generate a user token from the /api/token endpoint as described in Authenticating with a token.

Failed authentication

A request to generate a token from /api/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: User authentication failed status code.

Endpoints not requiring tokens 

You can access the following endpoints without a token or HTTPS "Authorization" header:

• /api/about: Returns a list of supported API versions and product information.
• /api/<version>/swagger.json: Returns the swagger definition of all endpoints in a given API version. For example, /api/v1.0/swagger.json.
• /api/token: Generates an expiring token for use when accessing other endpoints. 

Permissions

After successful authentication of a user, endpoints check whether the user has permission to perform the requested action. Users must be granted the same rights as if they were attempting the action through the equivalent user interface or command line tool. For example, if a user does not have the right to add a device to a particular realm in the user interface, that user cannot do it from the REST API either. If the user lacks the required right, a 403 Forbidden status code is returned by the endpoint.