Authentication

Retrieve authentication token

Returns a [JSON Web Token (JWT)](/developers/auth/jwts) `auth_token` for authenticating further requests to the API. <Note> 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](/developers/api-guidelines/rate-limits). </Note> ### 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](/developers/auth/multi-factor-authentication).

Request

Authenticate with an [application token](/developers/auth/application-tokens). <Info> **Temporary exception**: [User credentials](/developers/auth/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. </Info>
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_tokenstring

JWT authentication token (returned for successful authentication)

refresh_tokenstring

Refresh token (returned with auth_token for user credentials auth)

mfa_tokenstring

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

Errors

401
Unauthorized Error
404
Not Found Error