JWTs

JSON Web Tokens (JWTs) are signed JSON objects that authenticate your API requests. After you authenticate with application tokens or user credentials, 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
import requests
2
3
url = "https://cdn.emnify.net/api/v1/user"
4
5
payload = {
6
    "username": "eabbot@flatland.org",
7
    "name": "Edwin Abbott",
8
    "organisation": { "id": 123 },
9
    "roles": [{ "id": 1 }, { "id": 2 }]
10
}
11
headers = {
12
    "Authorization": "Bearer <token>",
13
    "Content-Type": "application/json"
14
}
15
16
response = requests.post(url, json=payload, headers=headers)
17
18
print(response.json())

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