Retrieve authentication token

POST

https://cdn.emnify.net/api/v1/authenticate

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).

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:

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.
MFA verification: Send the mfa_token with the 6-digit OTP code. Optionally include trusted_device information to skip MFA for 90 days.
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](/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

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error

$	curl -X POST https://cdn.emnify.net/api/v1/authenticate \
>	-H "Content-Type: application/json" \
>	-d '{
>	"application_token": "5cCI6IkpXVCJ9.."
>	}'

$	curl -X POST https://cdn.emnify.net/api/v1/authenticate \
>	-H "Content-Type: application/json" \
>	-d '{
>	"application_token": "5cCI6IkpXVCJ9.."
>	}'

1	{
2	"auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
3	}