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>"
}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') 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
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.
POST /api/users/logoutExamples
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)
Last updated