Authentication

Multi-factor authentication

When multi-factor authentication (MFA) is enabled for your account, you must complete a two-step verification process to authenticate.

MFA applies only when authenticating with user credentials. Use application tokens instead. They don’t require MFA handling and are the recommended authentication method for all API integrations.

Two-step authentication flow

1

Submit credentials and receive MFA token

Send your username and SHA-1 hashed password to /api/v1/authenticate. Instead of the usual auth_token, the server returns an mfa_token and sends a one-time password (OTP) to your registered email or authenticator app.

POST
/api/v1/authenticate
1curl -X POST https://cdn.emnify.net/api/v1/authenticate \
2     -H "Content-Type: application/json" \
3     -d '{
4  "username": "user@service.org",
5  "password": "8Y8knYSkeyYV23kd"
6}'
Try it
Response
1{
2  "mfa_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
3}
2

Verify OTP and receive auth token

Send the mfa_token from Step 1 along with the 6-digit OTP code to /api/v1/authenticate. If verification succeeds, the server returns your auth_token and refresh_token.

POST
/api/v1/authenticate
1curl -X POST https://cdn.emnify.net/api/v1/authenticate \
2     -H "Content-Type: application/json" \
3     -d '{
4  "mfa_token": "zI1NiIsInR5cCI6IkpXV...",
5  "code": "123456",
6  "trusted_device": {
7    "fingerprint": "zI1NiIsInR5cCI6IkpXV",
8    "operating_system": "Ubuntu 16.04.2 LTS (Xenial)",
9    "browser": "Mozilla Firefox"
10  }
11}'
Try it
Response
1{
2  "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
3  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
4}

Skip MFA with trusted devices

To avoid entering an OTP code on every login, you can register your device as trusted. Trusted devices skip the MFA verification step for 90 days.

Register a trusted device

Include the trusted_device object in your Step 2 request:

FieldRequiredDescription
fingerprintYesUnique identifier for the device (you generate this)
operating_systemNoDevice OS (for your reference)
browserNoBrowser name (for your reference)
nameNoFriendly name for the device

The fingerprint must be unique and consistent for each device. You’re responsible for generating and storing this identifier in your application.

Authenticate with a trusted device

Once registered, include the fingerprint in your initial authentication request. If the fingerprint matches a trusted device, the server returns auth_token and refresh_token immediately, skipping the OTP step.

POST
/api/v1/authenticate
1curl -X POST https://cdn.emnify.net/api/v1/authenticate \
2     -H "Content-Type: application/json" \
3     -d '{
4  "username": "user@service.org",
5  "password": "8Y8knYSkeyYV23kd",
6  "fingerprint": "zI1NiIsInR5cCI6IkpXV"
7}'
Try it
Response
1{
2  "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
3  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
4}

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

Manage MFA keys

Use the following endpoints to manage MFA keys and trusted devices:

EndpointDescription
Create MFA keyCreate a new MFA key for a user
Activate MFA keyActivate an MFA key with a 6-digit code
Delete MFA keyDelete an existing MFA key
Get MFA statusRetrieve available MFA statuses
Get MFA typesRetrieve available MFA types
List trusted devicesGet all trusted devices for a user
Delete trusted deviceRemove a trusted device

Errors

The following table lists errors that may occur during MFA operations.

ErrorCodeCause
401 Unauthorized-Password is invalid
409 Duplicated1405MFA key already exists
422 InvalidValue1400MFA key type is invalid
422 Required1400Password or type field missing

Solutions

  • 401 Unauthorized: Verify your password is correctly SHA-1 hashed before sending. Use the -n flag with echo to avoid trailing newlines.
  • 409 Duplicated: Delete the existing MFA key before creating a new one.
  • 422 InvalidValue: Get the available MFA types to find valid type IDs.
  • 422 Required: Include both type (with id) and password fields in your request body.