Skip to content

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.

Confirmation for creating a personal user key

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 readonly user cannot perform modifying requests.
  • 400 — check the request body and parameters against the API reference.