Authentication

All API methods require you to authenticate yourself. We use OAuth 2 for this, in particular we use the following grant types:

client_credentials to authenticate clients for non-user specific tasks
password to authenticate users
refresh_token to refresh a user token once it expires

POST /oauth/v2/token

Returns an access token valid for up to an hour.

Authenticating a client

Example request for client authentication:

POST /oauth/v2/token

{
  "grant_type": "client_credentials",
  "client_id": "abc123",
  "client_secret": "456789"
}

Example response for client authentication:

{
  "access_token": "MTI1ZWFkNDBmYjOGVmMGI0YzRjMGMzZGE4MQ",
  "expires_in": 3600,
  "token_type": "bearer",
  "scope": null
}

Authenticating a user

Example request for user authentication:

POST /oauth/v2/token

{
  "grant_type": "password",
  "client_id": "abc123",
  "client_secret": "456789",
  "username": "someone@example.com",
  "password": "def56789"
}

Example response for client authentication:

{
  "access_token": "MTI1ZWFkNDBmYjOGVmMGI0YzRjMGMzZGE4MQ",
  "expires_in": 3600,
  "token_type": "bearer",
  "scope": null,
  "refresh_token": "NmI5ZGI3MzBmZjYwY2E1ZTlkYTM4MTJlMmI1Z"
}

Refreshing a user access token

Example request for user authentication:

POST /oauth/v2/token

{
  "grant_type": "refresh_token",
  "client_id": "abc123",
  "client_secret": "456789",
  "refresh_token": "NmI5ZGI3MzBmZjYwY2E1ZTlkYTM4MTJlMmI1Z"
}

Example response for client authentication:

{
  "access_token": "ZDdkODE4Y2FkMzM4ZDcxZDIxM2M0ZjE2MTE4NG",
  "expires_in": 3600,
  "token_type": "bearer",
  "scope": null,
  "refresh_token": "YWYyMzI2ZjM1ZWVjODZhM2FkMWQwMTEzMjQ5NGF"
}

POST /otp/send

Request a OTP for a user

You can request a one time password for your users via email or SMS. You have to turn this on in your security settings for the REST API.

If you want to register new users as well, for unknown email addresses or mobile numbers, you can also turn on the “Allow new users” feature.

Please note that if “Allow new users” is disabled, this method will return a successful response even if the user does not exist in our database. This is to avoid user enumeration vulnerabilities and to reduce privacy implications.

Once your user receives the OTP, they can use it as a password, but they have limited time to do so. You can configure the OTP TTL settings in the control room, but make sure the OTP never lasts for more than a few minutes, 10 minutes is the default, and you should not exceed 30 minutes.

Example request for an OTP via email:

POST /otp/send

{
  "email": "someone@example.com"
}

Example payload for an OTP via mobile number:

{
  "phone": "02345678901234"
}

Example response:

{
  "data": {
    "email": "giovanni@satellite.co.nz"
  },
  "meta": []
}