JWTs

JSON Web Tokens (JWTs) are signed JSON objects that authenticate your API requests. After you authenticate with application tokens (or, temporarily, user credentials for specific cross-Workspace APIs), the API returns a JWT called auth_token.

Use the auth token

Include the auth_token in the Authorization header of every API request using the Bearer scheme:

1
Authorization: Bearer YOUR_AUTH_TOKEN

The following example shows how to include the auth_token when creating a new user:

1
curl -X POST https://cdn.emnify.net/api/v1/user \
2
     -H "Authorization: Bearer <token>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "username": "eabbot@flatland.org",
6
  "name": "Edwin Abbott",
7
  "organisation": {
8
    "id": 123
9
  },
10
  "roles": [
11
    {
12
      "id": 1
13
    },
14
    {
15
      "id": 2
16
    }
17
  ]
18
}'

JWT structure

A JWT consists of three parts separated by dots: header.payload.signature

Decode and inspect tokens

To inspect a JWT’s contents, use jwt.io or decode it in your application.

Example using Python:

1
import base64
2
import json
3
4
def decode_jwt(token):
5
    parts = token.split('.')
6
    payload = parts[1]
7
    # Add padding if needed
8
    payload += '=' * (4 - len(payload) % 4)
9
    decoded = base64.urlsafe_b64decode(payload)
10
    return json.loads(decoded)

Handle expired tokens

When your auth_token expires, API requests return a 401 Unauthorized error. To handle this:

1. Catch the 401 response in your application
2. Re-authenticate to get a new token (using your application token or refresh token)
3. Retry the failed request with the new token