Authentication

Authenticate to the Polarity v5 REST API

Overview

Authentication against the Polarity REST API requires acquiring a Bearer token. The token can then be used in subsequent requests to the API where authentication is required.

Authenticating

To begin, you will need to authenticate to the Polarity Server to obtain a reusable bearer token that will be used with subsequent authenticated requests.

To authenticate to the Polarity REST API you must send a POST request that includes an identification and password property in your JSON data payload to the /api/users/login endpoint:

Request Path
POST /api/users/login
Request Body
{
  "identification": "<USERNAME>",
  "password":"<PASSWORD>"
}

Acquiring a bearer token currently requires authenticating with a local or LDAP account.

Examples

curl -v -X POST https://<polarity-server>/api/users/login \
--header 'Content-Type: application/vnd.api+json' \
--data '{"identification": "<USERNAME>", "password":"<PASSWORD>"}'

Be sure to include the Content-Type header with a value of application/vnd.api+json

Return Payload

The request will return a JSON payload with a token in addition to the user’s settings:

{
  "data": {
    "token": "<AUTH_TOKEN>",
    "expiration_time": <UNIX_EPOCH_TIMESTAMP_IN_SECONDS>,
    "users": {
      ... // additional user attributes    
    }
  }
}

The token is tied to the identity of the requesting user and includes an expiration_time which is specified as a Unix Epoch Timestamp in seconds. You will then use the token in subsequent requests by including it in the Authorization header as a Bearer token:

'Authorization': 'Bearer <AUTH_TOKEN>'

HTTP Status Codes

Status Code
Result

200

Successful login

401

Invalid username or password

400

Malformed request payload

Refreshing a Token

You can refresh a token using the GET /api/users/refresh endpoint. By passing in the existing Token as part of the Authorization header, this endpoint will return a new token with a refreshed expiration. The format of the return payload is the same as the /api/users/login endpoint.

Examples

curl -v -X GET https://<polarity-server>/api/users/refresh\
--header 'Authorization: Bearer <AUTH_TOKEN>' \
--header 'Content-Type: application/vnd.api+json'

Invalidating a Token

Once you are done working with the REST API, you can invalidate the token by making a call to POST /api/users/logout using the token you wish to invalidate.

Request Path
POST /api/users/logout

Examples

curl -v -X POST \
https://<polarity-server>/api/users/logout \
--header 'Authorization: Bearer <AUTH_TOKEN>' \
--header 'Content-Type: application/vnd.api+json'

The endpoint will return a 200 HTTP Status Code is you are successfully logged out (i.e., the provided token is invalidated)

Last updated