User Authentication

All requests to the API must contain an auth_token in the request header. The /api/v1/authenticate resource is used to generate an auth_token in order to authenticate subsequent requests. There is a short validity period of 240 minutes for this token.

The refresh_token is valid for 350 minutes.

Request body

The request body to /api/v1/authenticate should contain the following:

  • username (String) required - The username, this is typically the email address used when signing up.
  • password (String) required - User password. If users have signed up using the SIM For Things System management interface, the password will need to be a SHA1 encrypted string.
  • fingerprint (String) optional - the “fingerprint” of a trusted device (if this device is already trusted, no MFA code needs to be provided)

POST /api/v1/authenticate:

{
  "username": "user@domain.com",
  "password": "2fd4e1c67a2d28fced849ee1bb76e7391b93eb12"
}

The server will respond with the following properties after a request with either username and password or a refresh_token:

  • auth_token (String) - Used to authenticate requests to the API
  • refresh_token (String) - Returned when authenticating with username and password or refresh_token

Response:

{
  "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Refresh Token

Due to the short expiry of the auth token, a refresh_token can be used to obtain a new auth_token without providing user credentials again.

  • refresh_token (String) - received after a successful authentication with username and password

POST /api/v1/authenticate:

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response:

{
  "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Basic Authentication