Skip to content

Authentication

Info

All the examples in this document assume you are using an instance of Arrigo Local installed on your local computer. Remember to change hostname and protocol (both http and ws) if you are testing against another computer:
http://localhost/arrigo/api → https://myserver.com/arrigo/api
ws://localhost/arrigo/api → wss://myserver.com/arrigo/api

Token based authentication

The API uses token based authentication and you obtain a token by logging in.

Whenever you access an authorized endpoint you must provide a valid auth token in the Authorization header of the request. To be specific the API uses the Bearer authentication scheme, which means that the Authorization header value must start with the text Bearer followed by a single whitespace and then the auth token you get when logging in:

Authorization: Bearer [your auth token]

Example:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhYW4iLCJqdGkiOiIzMzk4NzFjNy1mNmFjLTQwNjctYmUwNC1lNDIwZTc0YTFlNmQiLCJuYmYiOjE1NzkyNjI5MzAsImV4cCI6MTU3OTI2MzUzMCwiaWF0IjoxNTc5MjYyOTMwfQ.rreDnZpEWXFV7is7pi0Xl3oJ29zxXLF2zbeeGcWaOfg

Any attempt to access an authorized endpoint without the Authorization header set or with the wrong scheme returns 401 UNAUTHORIZED.

Logging in

You log in by posting your credentials (username and password) to the login endpoint:

POST http://localhost/arrigo/api/login
{
  "username": "[the username]",
  "password": "[the password]"
}

Example:
{
  "username": "demouser",
  "password": "abc123"
}

A successful login returns an Auth Token (AT), a Refresh Token (RT) and the expiration time of the AT in seconds:

200 OK
{
  "authToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhYW4iLCJqdGkiOiIzMzk4NzFjNy1mNmFjLTQwNjctYmUwNC1lNDIwZTc0YTFlNmQiLCJuYmYiOjE1NzkyNjI5MzAsImV4cCI6MTU3OTI2MzUzMCwiaWF0IjoxNTc5MjYyOTMwfQ.rreDnZpEWXFV7is7pi0Xl3oJ29zxXLF2zbeeGcWaOfg",
  "expires_in": 600,
  "refreshToken": "9d524a40-4c49-4bda-b6a5-8776e442311f"
}

The endpoint returns 400 BAD REQUEST if a malformed payload was posted or 401 UNAUTHORIZED if the credentials were invalid.

Accessing authorized endpoints

Various endpoints in the API (/graphql for example) requires a valid AT to be provided in the Authorization header.

See Token based authentication for more information.

Any attempt to access an authorized endpoint without the header or with an invalid token returns 401 UNAUTHORIZED.

Refreshing the token

The AT you get when logging in is valid for 10 minutes by default. After the AT expires any requests using that token will return a 401 UNAUTHORIZED. But by using the AT together with the RT you got when logging in you can exchange your stale AT for a new one and get another 10 minutes of access.

You have the choice of either keeping track of the AT expiration time and do a preemptive refresh or refreshing when receiving a 401 UNAUTHORIZED with the token-expired header set to true.

The RT has a default expiration time of 60 days. This means that a RT cannot be used for refreshing after that, and that a new login is required. But if you continuously use the API and refresh the AT you will basically never be logged out.

To get a new AT you post the RT to the refresh endpoint:

POST http://localhost/arrigo/api/login/refresh
{
  "refreshToken": "[your refresh token]"
}

Example:
{
  "refreshToken": "9d524a40-4c49-4bda-b6a5-8776e442311f"
}

Please note that although this is not an authorized endpoint you still have to provide the AT (you got together with the RT) in the Authorization header.

A successful refresh returns a new AT and RT:

200 OK
{
  "authToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhYW4iLCJqdGkiOiI1MjBlNzE3MS1hODZiLTQ3ZjEtYTlkMC0zZTBmM2JhNTA5MWIiLCJuYmYiOjE1NzkxODcyMzUsImV4cCI6MTU3OTE4NzgzNSwiaWF0IjoxNTc5MTg3MjM1fQ.p4lNaP1dYYiFKHwzOQ2lBeih_PJbZf1mGH3b3DCIocs",
  "expires_in": 600,
  "refreshToken": "daf5e75e-4490-42df-9107-5b16e378e052"
}

The endpoint returns 400 BAD REQUEST if the payload was malformed or 401 UNAUTHORIZED if the AT or RT was invalid.

Logging out

By "logging out" we mean revoking the RT so it can no longer be used for creating new AT's. AT's are not blacklisted when logging out! This means that it might possible to access authorized endpoints even after logout since the AT hasn't expired, but you cannot use that AT for refreshing. The AT will eventually expire and then become invalid.

There are two ways of logging out:

  • Post an empty request to the /logout endpoint with the currently active AT in the auth header.
  • Post the RT as payload to the /logout endpoint.
POST http://localhost/arrigo/api/logout
{
  "refreshToken": "[the refresh token]"
}

Example:
{
  "refreshToken": "9d524a40-4c49-4bda-b6a5-8776e442311f"
}

If both tokens are present in the request the AT takes precedence.

A successful logout returns 204 NO CONTENT, no AT and invalid RT returns 400 BAD REQUEST and if the AT is invalid token you get a 401 UNAUTHORIZED.

Verifying a token

The verification endpoint can be used to verify if a specific AT was issued by the server, and if the token still is valid.

POST http://localhost/arrigo/api/login/verify
{
  "authToken": "[the auth token]"
}

Example:
{
  "authToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhYW4iLCJqdGkiOiI1MjBlNzE3MS1hODZiLTQ3ZjEtYTlkMC0zZTBmM2JhNTA5MWIiLCJuYmYiOjE1NzkxODcyMzUsImV4cCI6MTU3OTE4NzgzNSwiaWF0IjoxNTc5MTg3MjM1fQ.p4lNaP1dYYiFKHwzOQ2lBeih_PJbZf1mGH3b3DCIocs"
}

The endpoint returns 204 NO CONTENT if the AT was issued by the server and if the token is still valid. All other cases returns 400 BAD REQUEST.