Authentication API

The /auth API endpoint

/auth (GET)

The /auth API endpoint provides HTTP GET access to create an access token using basic authentication.

EXAMPLE

In the following example, querying the /auth API with a given username and password returns a 200 OK response, indicating that the credentials are valid, along with an access and a refresh token.

curl -u myusername:mypassword http://127.0.0.1:8080/auth

HTTP/1.1 200 OK
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": 1544582187,
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

API Specification

/auth (GET)
description Generates an access token to the API using basic authentication. Access tokens last for around 15 minutes. When your token expires, you should see a 401 Unauthorized response from the API. To generate a new access token, use the /auth/token API endpoint.
example url http://hostname:8080/auth
output 
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": 1544582187,
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}
response codes
  • Valid credentials: 200 (OK)
  • Invalid credentials: 401 (Unauthorized)
  • Error: 500 (Internal Server Error)

The /auth/test API endpoint

/auth/test (GET)

The /auth/test API endpoint provides HTTP GET access to test user credentials.

EXAMPLE

In the following example, querying the /auth/test API with a given username and password returns a 200 OK response, indicating that the credentials are valid.

curl -u myusername:mypassword http://127.0.0.1:8080/auth/test

HTTP/1.1 200 OK

API Specification

/auth/test (GET)
description Tests a given username and password.
example url http://hostname:8080/auth/test
response codes
  • Valid credentials: 200 (OK)
  • Invalid credentials: 401 (Unauthorized)
  • Error: 500 (Internal Server Error)

The /auth/token API endpoint

/auth/token (POST)

The /auth/token API endpoint provides HTTP POST access to renew an access token.

EXAMPLE

In the following example, an HTTP POST request is submitted to the /auth/token API to generate a valid access token. The request includes the refresh token in the request body and returns a successful HTTP 200 OK response along with the new access token.

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
-H 'Content-Type: application/json' \
-d '{"refresh_token": "eyJhbGciOiJIUzI1NiIs..."}' \
http://127.0.0.1:8080/auth/token

HTTP/1.1 200 OK
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": 1544582187,
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

API Specification

/auth/token (POST)
description Generates a new access token using a refresh token and an expired access token
example url http://hostname:8080/auth/token
example payload 
{
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}
output 
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": 1544582187,
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}
response codes
  • Success: 200 (OK)
  • Malformed: 400 (Bad Request)
  • Error: 500 (Internal Server Error)