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

To authenticate a user, their username and password have to be posted to the token endpoint. This endpoint requires: - the client ID - the client secret - the grant type must be password - the username - the password

The password can be either a regular password set by the user, or a OTP (One Time Password). One time passwords can be requested either using a web form, or the Request a One Time Password (OTP) endpoint. The OTP are usually short lived, and are sent to the user via email or SMS.

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"
}

Request a One Time Password (OTP)

To request a one time password, you can send a user’s email address to the endpoint below. If the user does not exist, a new user might be created for them to login. This depends on the security settings of that particular TAG instance.

An email will be triggered to the specified email address, with the user’s short lived OTP in it. One time passwords can be used only once.

POST /otp/send

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

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"
}