Authentication

There are three methods of authentication available in all environments: JSON Web Token (JWT), API Key, and X-Signature.

JSON Web Token (JWT)

Submit your email and password to POST /api/v1/sign_in to receive a JWT.

For accounts with 2FA enabled, the first request (email + password only) will return HTTP 401 with:

{ "error": "OTP required", "otp_secret": "..." }

Re-submit the request including otp_attempt (your TOTP code) and otp_secret (the value returned above) to receive the token.

Once obtained, attach the JWT to every request using the Authorization header:

Authorization: {JWT token}

Tokens expire after 1 month, after which a new sign-in is required.

API Key

API keys are hashed (SHA-256 + salt) before storage. The plain token is provided to you once at creation time. Include it in the Authorization header:

Authorization: {API key}

X-Signature

X-Signature authentication requires two headers:

Authorization: {access_token} — the secret key's access token
X-Signature: {signature} — an HMAC-SHA256 signature of the request body, Base64-encoded

In case a request does not provide the authorization token, or the token provided is not valid, the response may return one of the following statuses:

401 Unauthorized — invalid or missing credentials
403 Forbidden — authenticated but not authorized for the requested resource
404 Not Found — JWT is valid but the associated user no longer exists
423 Locked — account locked due to too many failed sign-in attempts

For more information about errors, go to the Errors Section.