Skip to content

Authentication

API authentication is based on OAuth 2.0 protocol. The API uses JWT (JSON Web Token) or Cookies for authentication.

Authentication is required for all API requests. You can authenticate by sending an access token in the Authorization header. To get an access token, user need to log in with their username and password.

Note: Currently, cookies support has been disabled. Only JWT is supported.

To learn more about OAuth 2.0, visit OAuth 2.0.

To learn more about JWT, visit JWT.

Login request

To log in, send a POST request to /auth/jwt/login with application/x-www-form-urlencoded content type. The request body must contain the following parameters:

Request body:

  • grant_type - Must be password
  • username - Username of the user
  • password - Password of the user
  • scope - Optional - Scope of the token (currently not used)
  • client_id - Optional - Client ID (currently we use Account ID, which is provided during registration)
  • client_secret - Optional - Client Secret (currently not used)

Request Example:

POST /auth/jwt/login HTTP/1.1
Host: <api-url>:<port>
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Content-Length: 120

grant_type=password&username=******&password=******

Response:

The login request returns a JSON object containing the following parameters:

  • access_token - Access token
  • refresh_token - Refresh token
  • token_type - Type of the token (bearer)
  • expires_in - Time in seconds for how long the token is valid (1 hour)

Response example:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiOTIyMWZmYzktNjQwZi00MzcyLTg2ZDMtY2U2NDJjYmE1NjAzIiwiYXVkIjoiZmFzdGFwaS11c2VyczphdXRoIiwiZXhwIjoxNTcxNTA0MTkzfQ.M10bjOe45I5Ncu_uXvOmVV8QxnL-nZfcH96U90JaocI",
  "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiOTIyMWZmYzktNjQwZi00MzcyLTg2ZDMtY2U2NDJjYmE1NjAzIiwiYXVkIjoiZmFzdGFwaS11c2VyczphdXRoIiwiZXhwIjoxNTcxNTA0MTkzfQ.M10bjOe45I5Ncu_uXvOmVV8QxnL-nZfcH96U90JaocI",
  "token_type": "bearer",
  "expires_in": 3600
}

Client ID and Client Secret

The purpose of Client ID and Client Secret is to allow users to create multiple applications and use the same account to log in to all of them. For example, a user can create a mobile app and a web app. Both apps will use the same account to log in, but they will have different Client IDs and Client Secrets.

Another use case is to request a refresh token. The refresh token is used to get a new access token when the current one expires. The refresh token is only valid for a limited time and can only be used once. To get a refresh token, the user must provide Client ID and Client Secret.

Note: At the moment, the API does not use/process Client ID and Client Secret. For development purpose, we use Account ID as Client ID to refresh token. This way developers do not need to re-login, when the access token expires.

To learn more about Client ID and Client Secret, visit OAuth 8.2: Client ID and Client Secret.

Refresh token request

Simple refresh token request

Note: This request is currently in development, and will likely change in the future.

When the access token expires, the user can request a new access token by sending a POST request to /auth/jwt/refresh with the refresh tokens in the request header. The response will contain a new access token and a new refresh token.

Request header parameters:

  • refresh-token

Request example:

POST /auth/jwt/refresh HTTP/1.1
Host: <api-url>:<port>
refresh-token: <string>
Accept: application/json

Postman refresh token request

For development purposes, when using Postman, you should use /auth/jwt/postman-refresh endpoint to refresh the token. This endpoint will return a new access token and a new refresh token.

Postman Authentication

Authentication with cookies

Note: This feature is currently disabled.