Project Description

Authenticating with Okappy

The first step in using the Okappy API is to authenticate with Okappy using the following endpoint

POST /authentication

Authentication endpoint

Headers

Header Content
Authorise Basic token

The token should be a BASIC authorisation token comprised of the word ‘BASIC’ in capitals, followed by exactly one space, then a Base64 encoded string containing the username & password separated by a colon, e.g. “username:password”.

Parameters

No parameters

Responses

Code Description
200 Operation successful
400 Bad request
401 Unauthorised
429 Too many requests in a short period of time (please try again later)

Response entity

A 200 response will contain a text/plain string, which is a JSON object with the following structure:

{
"access_token" : <access_token>,
"token_type" : "Bearer",
"expires_in" : <int_seconds>:
}

The access_token field contains a JWT which should be used as the bearer token in subsequent requests.

The exp field of the JWT payload contains an epoch expiry date, which should be used for accurate scheduling of JWT refreshment.

Refreshing bearer tokens

To refresh a breaker token use

POST /authentication/refresh

Headers

Header Content
Authorise Basic token

The token should be a string taken from the “access_token” field of a response to an authorise request.

Parameters

No parameters

Responses

Code Description
200 Operation successful
400 Bad request
401 Unauthorised
429 Too many requests in a short period of time (please try again later)

Response entity

A 200 response will contain a text/plain string, which is a JSON object with the following structure:

{
"access_token": <access_token>,
"token_type": "Bearer",
"expires_in": <int_seconds>
}

The access_token field contains a refreshed JWT which should be used as the bearer token in subsequent requests.