Authentication
Access to the API requires authentication as a registered user. The privileges and access granted will be commensurate with the authenticated user. An authentication endpoint will return an authentication token which is a JSON Web Token (JWT).
The API is:
POST /auth/login
With a body including the Email address and Password of the account assuming a non-SSO, local account. SSO authentication will be described in an updated version of this document. An example body would be:
{
“email”: “somebody@localhost”,
“password”: “ThisIsAPrettySecureP@ssw0rd!”
}
Assuming a successful response with an HTTP 200 (Success) result, a JSON object is returned including:
- token – The JWT token to be used in subsequent API calls
- email – The email address of the logged in user
- id – The internal BE ID of the logged in user
The JWT token, documented in RFC-7519, decodes to include the user id, email, username as well as orig_iat (Original Issued-At time) and exp (Expiration) values to indicate when the token originated and expires.
Unsuccessful attempts would return an HTTP 400 (Bad Request) result. The error would follow standard error returns described below.
Authentication: Token Refresh
At any time before the expiration, a token can be refreshed without the original credentials. There is an overall expiration after which re-authentication is required for security, but this allows the core authentication tokens to expire more frequently provided the application periodically refreshes them.
The API to refresh a token is:
POST /auth/refresh
This is a JSON request and the body must include:
{
“token”: The token received either login or refresh
}
Assuming a successful response (HTTP 200), you will receive a JSON body including the updated token value. Use that value in subsequent API calls.