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>"}'

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://my-server')

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'

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://my-server')

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'

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)

PreviousModifying Integration Name & Acronym NextSearch Integrations

Last updated 9 months ago

hashtagOverview

hashtagAuthenticating

hashtagExamples

hashtagReturn Payload

hashtagHTTP Status Codes

hashtagRefreshing a Token

hashtagExamples

hashtagInvalidating a Token

hashtagExamples

Overview

Authenticating

Examples

Return Payload

HTTP Status Codes

Refreshing a Token

Examples

Invalidating a Token

Examples