Authenticating an API request¶
API v3 requests pass a token in the Authorization: Bearer <value> header. Choose authentication according to the integration's purpose. A personal user key and an administrative API token are different entities with different permissions and supported requests.
Access token¶
Sign in with the user's username and password:
curl --fail-with-body --request POST \
--user 'integration:ExamplePassword' \
'https://watcher.example.com/watcher/client-api/v3/login'
The response contains:
- access_token — a JWT for API requests, valid for one hour.
- refresh_token — a session identifier for obtaining a new
access_token. - server_info — server information, including the Watcher version.
Pass access_token in subsequent requests:
curl --fail-with-body \
--header 'Authorization: Bearer <access_token>' \
'https://watcher.example.com/watcher/client-api/v3/profile'
Admin API sign-in uses POST /watcher/admin-api/v3/login. It requires Watcher administrator access; the domain administrator role is insufficient for this sign-in.
Requesting a token without a username and password¶
When access_token expires, repeat /login, passing refresh_token:
curl --fail-with-body --request POST \
--header 'Authorization: Bearer <refresh_token>' \
'https://watcher.example.com/watcher/client-api/v3/login'
Save the tokens from the new response. If the session itself has ended or been revoked, you must sign in again with a username and password. Do not create a new session before every request: reuse the token obtained.
Personal user key¶
In the interface, open Profile → User and find API key. Click Create, or Reset if a key already exists, and confirm. See the profile guide for details.

To issue it through the API, send:
curl --fail-with-body --request POST \
--header 'Authorization: Bearer <access_token>' \
'https://watcher.example.com/watcher/client-api/v3/users/15/apikey'
Replace 15 with the user identifier. You can obtain your own identifier through GET /profile. The response has the form {"apikey":"<key>"}. Pass the key as Bearer; it performs requests with the user's current permissions. It has no separate expiration; disabling the user prevents its use.
GET /users/{user_id}/apikey reads an existing key. A repeated POST replaces it: the previous key stops working for new requests. The user or someone authorized to access their protected data, including a Watcher administrator, can issue or read the key. Protect it like a password.
Scoped API token¶
A Watcher system administrator can create a separate token through POST /watcher/admin-api/v3/api_tokens. Its body contains name and a permissions list with scopes. This token is suitable only for operations supporting the relevant scope; it is not a universal replacement for a user key.
For example, autologin generation uses the autologin/generate scope:
{
"name": "billing-autologin",
"permissions": [{"scopes": ["autologin/generate"], "execute": true}]
}
Pass the resulting key as Bearer. See autologin for usage.
Domain configuration tokens¶
Separate domain configuration tokens are provided for server-side billing integration with Lumika. Issuing them through Settings → API tokens, their config/ scopes and lifecycle are described in the Lumika integration guide. A system or domain administrator manages this form. It selects configuration permissions; the autologin/generate scope from the example above is not issued through this form. A personal user key is created in Profile.
Diagnosing access errors¶
- 401 — check the token and session state; for an expired JWT, try refreshing through
/login. - 403 — check the user role, permissions in the specific Organization and token permissions. A
readonlyuser cannot perform modifying requests. - 400 — check the request body and parameters against the API reference.