Skip to navigation
AuthenticationApplication tokens

Application tokens

Application tokens are the recommended way to authenticate with the emnify REST API for machine-to-machine (M2M) communications. Unlike user credentials, application tokens don’t require storing passwords on your servers or dealing with multi-factor authentication (MFA).

Key benefits:

  • Create multiple tokens for different applications or environments
  • Give each token a role that limits what it can access
  • Restrict tokens to specific IP address ranges
  • Set expiration dates for automatic revocation
  • Revoke individual tokens at any time without affecting others

Security best practices:

  • Give each token the most limited role that fits its integration
  • Use IP restrictions when your server has a static IP
  • Store tokens in environment variables, never in source code
  • Rotate tokens periodically and revoke unused tokens

Application tokens are scoped to the Workspace where they were created. Two cross-Workspace operations (Workspace switching and cross-Workspace SIM transfers) temporarily require user credentials, but these APIs are being updated to support application tokens.

Create an application token

To create an application_token, send a POST request to /api/v2/application_token with these fields:

  • name (required): a name that identifies the token, from 2 to 64 characters.
  • roles (required): an array with exactly one role, which sets what the token can do. For the role IDs, see Assign a role to every new token.
  • expiry_date (required): the date and time the token expires, at least one day and at most 10 years in the future.
  • ip_restrictions (optional): the IPv4 addresses or CIDR ranges the token can connect from. Leave it out to allow any address.
POST
/api/v2/application_token
curl -X POST https://cdn.emnify.net/api/v2/application_token \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "name": "CI pipeline token",
  "roles": [
    {
      "id": 3
    }
  ],
  "expiry_date": "2027-08-21T10:00:00.000Z",
  "ip_restrictions": [
    "192.168.0.1",
    "10.10.1.0/24"
  ]
}'
Try it

The response contains the token in the token field. Store it right away, because you can’t retrieve it later.

Response
{
  "id": 1234,
  "name": "CI pipeline token",
  "status": {
    "id": 1,
    "description": "ACTIVE"
  },
  "roles": [
    {
      "id": 3,
      "name": "Observer"
    }
  ],
  "created_date": "2026-08-21T10:00:00.000Z",
  "ip_restrictions": [
    {
      "id": 41,
      "ip_address": "192.168.0.1/32"
    },
    {
      "id": 42,
      "ip_address": "10.10.1.0/24"
    }
  ],
  "expiry_date": "2027-08-21T10:00:00.000Z",
  "created_by": {
    "id": 10,
    "username": "john.doe@example.com",
    "type": {
      "id": 0,
      "description": "HUMAN"
    },
    "name": "John Doe"
  },
  "token": "em_Kf3xR9vB2pLm7Qk4tZ..."
}

By default, the create endpoint refuses a new token when a Workspace holds 300 active application tokens. Deleted tokens don’t count toward the limit. If your integration needs more, contact your emnify account manager.

The v1 endpoints for managing application tokens (/api/v1/application_token) are deprecated and stop working on June 1, 2027. Authenticating with POST /api/v1/authenticate isn’t affected. To move your integration to v2, see Migrate to the v2 application token API.

Application tokens start with em_ and are opaque strings. Treat them as secrets and don’t parse them. To see when a token expires, read expiry_date from the create or list response. Tokens created in the earlier format keep working.

You can revoke the application token at any time.

You can also create and view application tokens in the emnify Portal.

For step-by-step instructions, see Application tokens.

Assign a role to an application token

Every application token has exactly one role, and the token can only call the operations that role allows. Roles work the same way for tokens as for users, so a token with the Observer role can read data but can’t change it.

  • To choose the role, pass its ID in roles when you create a token with the v2 endpoint. The Support role can’t be assigned to a token.
  • To change the role later, send the new role in roles to update the application token. The new role applies to auth_tokens generated after the change, and an existing auth_token keeps the old role until it expires. The expiry date and IP restrictions can’t be changed after you create the token.
  • The v1 create endpoint has no role selection, so every token it creates has the Administrator role.

A token with the Administrator role can do anything in your Workspace. If it leaks, an attacker gets the same access, so choose the most limited role that fits the integration.

Authenticate with an application token

Once you create an application token, use /api/v1/authenticate to generate a JWT auth_token that authenticates subsequent API calls.

POST
/api/v1/authenticate
curl -X POST https://cdn.emnify.net/api/v1/authenticate \
     -H "Content-Type: application/json" \
     -d '{
  "application_token": "em_Kf3xR9vB2pLm7Qk4tZ..."
}'
Try it
Response
{
  "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

The server returns only an auth_token. The response doesn’t include a refresh_token.

Handle token expiration

When an application token expires or is revoked:

  • Any auth_token generated from it remains valid until its own expiration
  • New authentication attempts with the expired application token fail with a 401 Unauthorized error
  • You need to create a new application token and update your application configuration

To avoid service interruptions:

  1. Set up monitoring for authentication failures
  2. Create a new application token before the current one expires
  3. Update your application to use the new token
  4. Revoke the old token after the transition is complete

Use an SDK

If you prefer to use an SDK instead of direct API calls: