Skip to navigation
AuthenticationRetrieve authentication token

Retrieve authentication token

Required permissions Beta Learn more

Public endpoint. No permission required.

Returns a JSON Web Token (JWT) auth_token for authenticating further requests to the API.

This API path has a rate limit of 100 requests per IP in a 5-minute window. Make sure to store your authentication token to avoid hitting this limit. For more information, see Rate limits.

Multi-factor authentication flow

When multi-factor authentication (MFA) is enabled for a user account:

  1. Initial login: Send your username and SHA-1 hashed password. If MFA is enabled and the device isn’t trusted, you receive an mfa_token instead of auth_token in the response and a one-time password (OTP) via email.
  2. MFA verification: Send the mfa_token with the 6-digit OTP code. Optionally include trusted_device information to skip MFA for 90 days.
  3. Subsequent logins: If you included a trusted device fingerprint during verification, send your username and SHA-1 hashed password with the fingerprint to bypass MFA.

For more information, see Multi-factor authentication.

Request

Authenticate with an application token.

Temporary exception: User credentials are currently required for operations that span multiple workspaces, such as switching between workspaces or transferring SIMs. These APIs are being updated to support application tokens.

application_tokenstringOptional
Application token for authentication
usernamestringOptional
Username for user credentials authentication
passwordstringOptionalformat: "password"

User password. Must be SHA-1 hashed when authenticating with user credentials.

fingerprintstringOptional

Device fingerprint for trusted device authentication (skips MFA)

refresh_tokenstringOptional

Refresh token to obtain a new auth_token

mfa_tokenstringOptional
MFA token received when MFA is enabled
codestringOptional=6 characters

6-digit one-time password (OTP) for MFA verification

trusted_deviceobjectOptional

Device information to register as trusted (90-day MFA exemption)

Response

Successful Authentication Request
auth_tokenstringOptional

JWT authentication token (returned for successful authentication)

refresh_tokenstringOptional

Refresh token (returned with auth_token for user credentials auth)

mfa_tokenstringOptional

MFA token (returned instead of auth_token when MFA is enabled and device isn't trusted)

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error