Authentication & Authorization

For authentication & authorization, PoS API use JSON Web Tokens (JWTs).

Authenticate requests

The API will reject any request that does not include a valid JWT in the HTTP Authorization Header. Thus, the first step is to retrieve a valid JWT from our authorization service.

Retrieve a valid access token

Following request will call our authorization service over HTTPS with private credentials in order to retrieve a temporary access_token(JWT).

Auth request
    
 
curl --request POST \     --url https://{{AUTHORIZATION_SERVICE_URI}}/oauth/token \     --header 'Content-Type: application/json' \     --data '{       "client_id": {{AUTH_CLIENT_ID}},       "audience": {{AUTH_AUDIENCE}},       "scope": "offline_access",      # Optional: only if you implement refresh_token logic (see below)       "grant_type": "password",       "username": {{PRIVATE_USERNAME}},       "password": {{PRIVATE_PASSWORD}}     }'
Copy

Auth response
    
 
{    "access_token": <valid_jwt>,    "refresh_token": <token_to_renew_access_without_username_password>,    "expires_in": <validity_period_in_seconds_from_now>,    "token_type": "Bearer"}
Copy

Make authenticated requests to PoS API

Each request to the PoS API will require a valid access_token (JWT) in the HTTP Authorization header using the Bearer authentication scheme. Use the access_token previously retrieved in every requests to the PoS API.

PoS API - Request example
    
 
curl --request GET \     --url 'https://{{POS_API_URI}}/api/v2/...' \     --header 'Authorization: Bearer {{access_token}}'
Copy

PoS API will respond with HTTP 401 Unauthorized if the access token used is not valid or has expired.

Renew the access

As the access token is valid during a limited amount of time, it is necessary to renew the token once expired. The renewal can be done using the same initial request to the authorization service (see Retrieve a valid access token) or via a refresh_token.

Use refresh token to implement sliding sessions

Sliding sessions are sessions that can be extended in order to only expire after a period of inactivity. For this purpose, a refresh token is handy: the access can be renewed without prompting the user to add his username and password again.

Auth response - Extract
    
 
{  "access_token": <valid_jwt>,  "refresh_token": <token_to_renew_access_in_the_future>,  ...}
Copy

Auth request with refresh token
    
 
curl --request POST \     --url https://{{AUTHORIZATION_SERVICE_URI}}/oauth/token \     --header 'Content-Type: application/json' \     --data '{       "client_id": {{AUTH_CLIENT_ID}},       "audience": {{AUTH_AUDIENCE}},       "grant_type": "refresh_token",     "refresh_token": {{REFRESH_TOKEN}}     }'
Copy

Use expires_in to optimise the access renewals

In theory, the client can retrieve a new access_token before each request, but this is obviously not optimal from a performance point of view. Instead, the client could store the number value contained in expires_in in the some local storage or cache after a first valid access token was retrieved. Then, this value can be used to only renew the access when needed.

Auth response - Extract
    
 
{  "access_token": <valid_jwt>,  "expires_in": <validity_period_in_seconds_from_now>,  ...}
Copy

Communication over TSL/SSL

The Chimpy POS API allows communication only via HTTPS (Hypertext Transfer Protocol Secure). All data is secured via Transport Layer Security protocol (TLS) that ensures encryption, data integrity and authentication of requests.

Last updated on