User Authentication with Multi-factor Authentication

Warning: To improve security across our services, authentication with user credentials has now been deprecated and will be removed on March 28, 2024. Please authenticate with application tokens instead.

See the deprecation notice for more information about why emnify is making this change.

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

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

Property	Type	Description
`id`	Integer	Unique identifier of this MFA key
`status`	Object	Information about the MFA key status (see Status Object)
`type`	Object	Information about the MFA key type (see Type Object)
`secret_key`	String	A Base32 encoded secret key for this MFA key Note: This only displays on creation
`otpauth`	String	The secret key, but URI-encoded for QR codes Note: This only displays on creation
`creation_date`	Timestamp	Date/time when this MFA key was created Type: ISO 8601 timestamp format
`activation_date`	Timestamp	Date/time when this MFA key was activated Type: ISO 8601 timestamp format

Status Object

Property	Type	Description
`id`	Integer	Status ID of this MFA key
`description`	String	Description of the status

Type Object

Property	Type	Description
`id`	Integer	Type ID of this MFA key
`description`	String	Description of the type

Errors

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

HTTP Status	Error Code	Error Token	Description	Scenario
401	-	-	Unauthorized	Given password is invalid
409	1405	Duplicated	MFA already activated	Can’t create a new MFA key if there is already one active
422	1400	InputValidationFailed	InvalidValue	MFA key type is invalid
422	1400	InputValidationFailed	Required	MFA key password or type is required