authentication

Retrieve authentication token

<Info icon="fa-light fa-lock-open" className="permission-callout"> <div className="permission-callout__header"><span className="permission-callout__title"><span className="permission-callout__label">Required permissions</span> <span className="fern-docs-badge small blue subtle rounded-full permission-callout__beta">Beta</span></span> <span className="permission-callout__learn-more">[Learn more](/developers/api-guidelines/permissions#how-permissions-work)</span></div>

Public endpoint. No permission required. </Info>

Returns a JSON Web Token (JWT) 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.

post/api/v1/authenticate

Request

  • Base URL: https://cdn.emnify.net
  • URL: https://cdn.emnify.net/api/v1/authenticate
  • Auth: none declared

Request body

application_tokenstring

Application token for authentication

usernamestring

Username for user credentials authentication

passwordstring password

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

fingerprintstring

Device fingerprint for trusted device authentication (skips MFA)

refresh_tokenstring

Refresh token to obtain a new auth_token

mfa_tokenstring

MFA token received when MFA is enabled

codestring

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

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)

Changes

No recorded changes to this operation across all 1 revision of this API.