Authentication & Tokens

This page explains how to authenticate against our REST APIs and how to use the returned JWT tokens when calling other endpoints.

You’ll learn how to:

  • Log in and obtain a JWT token

  • Send the token in the X-Authorization header

  • (Optionally) refresh tokens, if enabled

  • Understand what your token can access, based on your role

1. Overview

We use JWT (JSON Web Tokens) for user authentication.

Basic flow:

  1. Send username & password to the login endpoint.

  2. Receive a JWT token in the response.

  3. Include the token in all subsequent REST calls:

    • X-Authorization: Bearer <JWT_TOKEN>

If your token is invalid, expired, or missing, the API will respond with 401 Unauthorized.

For entity/role background, see
Core Concepts & Roles

2. Login: Getting a JWT Token

2.1 Endpoint

Full example (pseudo):

POST <BASE_URL>/api/auth/login
Content-Type: application/json

{
  "username": "user@example.com",
  "password": "your_password_here"
}

2.2 Example: curl

curl -X POST "<BASE_URL>/api/auth/login" \ -H "Content-Type: application/json" \ -d '{ "username": "user@example.com", "password": "your_password_here" }'


2.3 Typical Response

The response is a JSON object that includes at least a JWT token.
The exact structure may vary slightly by versions and configuration, but conceptually it looks like:

{ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....", "refreshToken": "optional-refresh-token-if-enabled"}

Key fields (conceptual):

  • token – the access token (JWT) you must send with all API calls.

  • refreshToken – if configured, allows you to get a new access token without re-entering credentials.


    After login, store the token securely in your script/service and use it in all subsequent REST calls.


3. Using the Token in API Calls

Once you have the token, you must include it in the X-Authorization header:

X-Authorization: Bearer <JWT_TOKEN>


3.1 Example: Get Telemetry for a Device

curl -X GET "<BASE_URL>/api/plugins/telemetry/DEVICE/<DEVICE_ID>/values/timeseries?keys=temperature" \
-H "X-Authorization: Bearer <JWT_TOKEN>"

Without this header (or with an invalid token) you will get 401 Unauthorized.


4. Checking Who You Are (Current User Info)

You can verify which user and role your token represents via:

  • Method: GET

  • Path: /api/auth/user

    curl -X GET "<BASE_URL>/api/auth/user" \
    -H "X-Authorization: Bearer <JWT_TOKEN>"

Typical response (simplified):

{ "id": { "id": "..." },
"name": "John Doe",
"email": "user@example.com",
"authority": "TENANT_ADMIN",
"tenantId": { "id": "..." },
"customerId": { "id": "..." }
}


5. Logout

If you need to explicitly invalidate a token (e.g. for UI/session-based flow), you can use logout:

  • Method: POST

  • Path: /api/auth/logout

curl -X POST "<BASE_URL>/api/auth/logout" \
-H "X-Authorization: Bearer <JWT_TOKEN>"

For server-to-server integrations, logout is often not required; tokens simply expire after their lifetime.