General

API version

All the methods share the common URL prefix: /api/<version>, where version is the major portion API version number. For instance, 1.2, 1.1 and 1.0 will all have the prefix /api/1, 2.0 will have the prefix /api/2.

Authentication

The API methods support both Basic HTTP authentication as well as Java Web Token (JWT) based authentication. The former should be used for built-in accounts while the latter – for external identity providers such as Google OAuth. The JWT authentication takes precedence over the Basic authentication so if both methods are specified the JWT authentication is used.

Basic Authentication

For the Basic auth every request should include the Authorization header:

Authorization: Basic <ENCODED-CREDENTIALS>

where the ENCODED-CREDENTIALS string is the base64 encoded pair of the user email and password delimited by the colon:

<email>:<password>

For curl the following command line options should be added:

curl --basic --user <email>:<password>

JWT Authentication

First, a user has to obtain their “refresh token” by opening in a browser the following URL:

https://<TONOMI-TENANT>/refreshToken

and authenticating with their email. When the authentication succeeds the user will see their refresh token, which should be saved and kept in a secure place.

Note

The generated refresh token is displayed to the user only once and if the token is lost, it cannot be restored and a new refresh token should be generated.

Note

It is strictly discouraged to generate new refresh tokens needlessly since too many requests from a single user may be treated as a security alert and may lead to preventive blocking the users requests.

Then a user should obtain a session token using the following API call:

POST /refreshToken/jwtBearer

Generates and returns the session token from the passed refresh token.

Status Codes:

Request body:

{
  "refreshToken" : "<PLACE-REFRESH-TOKEN-HERE>"
}

Response body:

{
  "jwtBearer" : "GENERATED-SESSION-JWT-BEARER",
  "expiresIn" : 36000 // expiration time in seconds
}

The retrieved session token is returned in form of Java Web Token (or JWT). This API method should be called to retrieve a new session token each time the previous one is expired. The exact expiration time can be retrieved from the Java Web Token itself, please see the specs for details.

Note

It is highly recommended not to generate a new session token until the previous one is expired. The exact expiration time can be extracted from the JWT itself. For details please see Java Web Token.

Having a valid JWT the user can call API methods by adding the following Authorization header:

Authorization: Bearer <SESSION-JWT-BEARER>

Data types

  • uuid: a 24-character hexadecimal string, such as 5163ae31e4b052964c25c78f.