Authentication

User credentials

Multi-factor authentication (MFA) is enforced for all enterprise users and cannot be disabled. If your account has MFA enabled, authenticating via the API requires handling the multi-step MFA flow, which can complicate automated integrations.

Application tokens are recommended for most API integrations. However, user credentials are required for operations that span multiple Workspaces:

  • Switching between Workspaces using /api/v1/authenticate/workspace
  • Transferring SIMs between Workspaces

Application tokens are scoped to a single Workspace and cannot access other Workspaces.

The /api/v1/authenticate API is used to generate a JSON Web Token (JWT) auth_token which authenticates subsequent API calls. You must provide a username (typically the email address used when signing up) and a SHA-1 hashed password in the request body. In turn, you receive an 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  "username": "user@service.org",
5  "password": "8Y8knYSkeyYV23kd"
6}'
Try it

The password needs to be a SHA-1 hashed string. You can generate a SHA-1 hashed password online or in the terminal via the following command:

$echo -n 'my_password' | openssl sha1
Response
1{
2  "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
3  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
4}

Refresh token

The server responds with an auth_token and refresh_token after you successfully authenticate. The auth_token is valid for 240 minutes for this token and so the refresh_token can be used to obtain a new auth_token without providing user credentials again.

POST
/api/v1/authenticate
1curl -X POST https://cdn.emnify.net/api/v1/authenticate \
2     -H "Content-Type: application/json" \
3     -d '{
4  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
5}'
Try it
Response
1{
2  "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
3}

Important:

  • The auth_token is valid for 240 minutes and the refresh token is valid for 350 minutes.
  • The refresh_token can only be used once and becomes invalid if you log in from somewhere else (for example, different web client).
  • When the auth_token has expired, you need to re-authenticate with the refresh token or again with the user credentials for a new auth_token. If both the authentication and refresh tokens have expired, you need to authenticate again.