Authentication

Multi-factor authentication

To improve security across emnify services, authentication with user credentials was deprecated and removed on March 28, 2024. Please authenticate with application tokens instead.

If you have multi-factor authentication (MFA) enabled for your account, authentication is performed in two steps:

  1. The first request submits user credentials (username and password) to return an mfa_token in the response instead of the usual auth_token and refresh_token.
  2. The second request sends this mfa_token and the generated one-time password (OTP) code to return the auth_token and refresh_token in the response.

For the second request, provide the following fields:

  • mfa_token (String, required) - JSON Web Token (JWT) returned from the first request
  • code (String, required) - OTP code
  • trusted_device (Object, optional) - Device details to determine if the second MFA step is skipped in the future

This data is stored if the second request is successful and includes the trusted_device object with the fingerprint, operating system, and browser.

Providing an MFA code is unnecessary if the device is already trusted. So, if the first request includes a unique identifier (known as a “fingerprint”) for a device that matches the fingerprint of a trusted device for your account, the auth_token and refresh_token are returned immediately. A device remains trusted for 30 days.

MFA key object

The following table describes the properties of the MFA key object.

PropertyTypeDescription
idIntegerUnique identifier of this MFA key
statusObjectInformation about the MFA key status (see Status object)
typeObjectInformation about the MFA key type (see Type object)
secret_keyStringA Base32 encoded secret key for this MFA key
Note: This only displays on creation
otpauthStringThe secret key, but URI-encoded for QR codes
Note: This only displays on creation
creation_dateTimestampDate/time when this MFA key was created
Type: ISO 8601 timestamp format
activation_dateTimestampDate/time when this MFA key was activated
Type: ISO 8601 timestamp format

Status object

PropertyTypeDescription
idIntegerStatus ID of this MFA key
descriptionStringDescription of the status

Type object

PropertyTypeDescription
idIntegerType ID of this MFA key
descriptionStringDescription of the type

Errors

The following table lists errors that may occur with this call.

HTTP StatusError CodeError TokenDescriptionScenario
401--UnauthorizedGiven password is invalid
4091405DuplicatedMFA already activatedCan’t create a new MFA key if there is already one active
4221400InputValidationFailedInvalidValueMFA key type is invalid
4221400InputValidationFailedRequiredMFA key password or type is required