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:

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

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

Bearer tokens are not available via SAML authentication.

Examples

CURL

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

Python

def get_auth_token(username, password, host):
    url = f"{host}/api/users/login"

​    payload = json.dumps({
        "identification": username,
        "password": password
    })

​    headers = {
        'Content-Type': 'application/vnd.api+json'
    }
​    response = requests.request("POST", url, headers=headers, data=payload)
    response.raise_for_status()
​
    body = response.json()
​
    return body['data']['token'];
    
token = get_auth_token('username', 'password', 'https://polarity.server.url') 

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

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

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

Python

def refresh_token(token, host):
    url = f'{host}/api/users/refresh'
​
    payload = {}
    headers = {
        'Content-Type': 'application/vnd.api+json',
        'Authorization': f'Bearer {token}'
    }
​
    response = requests.request('POST', url, headers=headers, data=payload)
    response.raise_for_status()
    
    body = response.json()
​
    return body['data']['token'];    
    
new_token = refresh_token('my-token', 'https://polarity.server.url')   

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.

Examples

CURL

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

Python

def logout(token, host):
    url = f"{host}/api/users/logout"
​
    payload = {}
    headers = {
        'Content-Type': 'application/vnd.api+json',
        'Authorization': f'Bearer {token}'
    }
​
    response = requests.request("POST", url, headers=headers, data=payload)
    response.raise_for_status()
    
logout('my-token', 'https://my-server')  

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