API Keys

API keys provide a simpler alternative to password-based authentication for the ThingsBoard REST API. Unlike JWT tokens, which require a login request and expire periodically, API keys are long-lived credentials that remain valid until they expire or are manually revoked.

API keys can be created for your own account or for other platform users, depending on your permissions.

1. In the top-right corner, click the three-dot menu and select Account.
2. Navigate to the Security tab.
3. In the API keys section, click the Manage button.
4. Click the + Generate button.
5. Enter a description for the API key (e.g., Production server, Testing environment).
6. Select the expiration period.
7. Click Generate.

Click the three-dot menu and select Account. Navigate to the Security tab. Click Manage in the API keys section. Click + Generate, enter a description, and set the expiration. Copy the generated API key — it will not be shown again. The new API key appears in the list.

A system administrator can create API keys for users of any tenant; a tenant administrator can create them for their customer users.

1. Navigate to the Customers or Users section.
2. Click the desired user to open their details.
3. Go to the API keys tab.
4. Click the + Generate button.
5. Enter a description for the API key.
6. Select the expiration period.
7. Click Generate.

Navigate to the Users section and click on a user. Go to the API keys tab. Click + Generate, enter a description, and set the expiration. The API key is created for the selected user.

Include the API key in the X-Authorization header with the ApiKey prefix:

X-Authorization: ApiKey $YOUR_API_KEY_VALUE

Example:

curl -X GET --header 'Accept: application/json' \
            --header 'X-Authorization: ApiKey $YOUR_API_KEY_VALUE' \
            'https://$THINGSBOARD_HOST_NAME/api/auth/user'

Replace $YOUR_API_KEY_VALUE with your API key and $THINGSBOARD_HOST_NAME with your ThingsBoard hostname.

When using Swagger UI, you can authenticate with an API key:

1. Open Swagger UI.
2. Click the Authorize button.
3. In the API key form (apiKey) section, enter your API key value with the ApiKey prefix:

   ApiKey YOUR_API_KEY_VALUE

4. Click Authorize.

Click the Authorize button in Swagger UI. Enter your API key with the ApiKey prefix and click Authorize.

Each API key in the table displays:

Available actions for each API key:

• Enable / disable — use the toggle to temporarily disable or re-enable a key.
• Delete — click the delete icon to permanently remove a key. This action cannot be undone.
• Edit description — click the edit icon to update the key’s description.