Authentication

Before making any authenticated calls to the API, the user needs to log in through our auth endpoint. The returned access_token must be added as an HTTP Header for REST API calls, e.g.: Authorization: Bearer <access_token>.

If the API returns the error code 1005, the access_token needs to be refreshed with the refresh endpoint.

The access_token is valid for 1 hour. The refresh_token is valid for 30 days.

POST /auth/login

Request

{
  "email": "<YOUR_EMAIL>",
  "password": "<YOUR_PASSWORD>"
}

Response

OK

{
  "success": true,
  "data": {
    "id_token": "a token for user identification",
    "access_token": "a token authorizing the user to perform certain actions",
    "refresh_token": "a token to get a new access_token after the old one expired"
  }
}

Error

  • BadRequestError
    • http status code: 400
{
  "success": false,
  "error_code": 3001,
  "error_message": "BadRequest"
}
  • InternalServerError
    • http status code: 500
{
  "success": false,
  "error_code": 2001,
  "error_message": "Internal Server error"
}
  • WrongUserNamePasswordError
    • http status code: 401
{
  "success": false,
  "error_code": 3002,
  "error_message": "Wrong username or password"
}
  • RequirePasswordChangeError
    • http status code: 401
{
  "success": false,
  "error_code": 1004,
  "error_message": "A Password change is required"
}
  • MissingTokenError
    • http status code: 401
{
  "success": false,
  "error_code": 1001,
  "error_message": "Authorization header missing or invalid"
}
  • RefreshTokenInvalidError
    • http status code: 401
{
  "success": false,
  "error_code": 1006,
  "error_message": "Refresh token is invalid"
}

POST /auth/refresh

Request

{
  "access_token": "the access_token used before (can be expired)",
  "refresh_token": "the refresh_token returned from login"
}

Response

{
  "success": true,
  "data": {
    "id_token": "a token for user identification",
    "access_token": "a token authorizing the user to perform certain actions"
  }
}