Skip to content
ABRQ DATADocs Abrq DIP · latest
Product page Request a trial
On this page

API Tokens

What API tokens are#

API tokens are per-user bearer credentials for calling the Abrq DIP API from scripts, CI, or schedulers — anywhere an interactive login is impractical. A token authenticates as its owning user and can never do more than that user's roles allow.

Tokens are presented in the format abrq_ followed by a 43-character URL-safe secret. The abrq_ prefix is how the API distinguishes a token from a JWT. Only a SHA-256 hash of the secret is stored server-side; the UI keeps just the last four characters as a display hint.

Creating a token#

  1. Open Settings → API Tokens and select New token.
  2. Give it a name that identifies the system that will use it (for example ci-deploy).
  3. Optionally set an expiry date. Leave blank for a non-expiring token.
  4. Select Create token.

The full plaintext token is shown exactly once, in the confirmation panel. Copy it immediately and store it in your secret manager — it cannot be retrieved again, only revoked and re-issued.

Warning. Treat tokens like passwords. Anyone holding the token acts as you, with your roles, until it is revoked or expires.

Scope: read or write#

Every token carries a scope, read or write:

  • write (the default) — the token can do whatever its owner can.
  • read — the token is confined to safe HTTP methods (GET, HEAD, OPTIONS).

Scope is enforced centrally in the authentication layer, not per endpoint: a read-scoped token that calls any state-changing method receives 403 before the handler runs, so a newly added endpoint can never be missed by the guard.

The Settings UI creates write-scoped tokens; to mint a read-scoped token, pass "scope": "read" when creating it through the API:

curl -X POST "https://<YOUR_DIP_HOST>/api/v1/users/me/api-tokens" \
  -H "Authorization: Bearer <ACCESS_JWT>" \
  -H "Content-Type: application/json" \
  -d '{"name": "readonly-reporting", "scope": "read", "expires_at": null}'

Using a token#

Send it as a standard bearer credential:

curl -H "Authorization: Bearer abrq_<TOKEN>" \
  "https://<YOUR_DIP_HOST>/api/v1/cdc-tables"

Each successful use stamps the token's Last used timestamp, visible in the Settings list — a quick way to spot stale or unexpectedly active tokens.

Revoking a token#

Revoke on a token's row disables it immediately after a confirmation — any client using it fails on its next request. Revocation cannot be undone; issue a new token instead.

Tokens also stop resolving when:

  • their expiry passes, or
  • their owning user is deactivated — token resolution checks that the owner is still active, so disabling a user kills all of that user's tokens at once (see User management).

Admin oversight#

The Settings tab manages your own tokens. Admins can additionally list and revoke any user's tokens through the API:

  • GET /api/v1/users/<USER_ID>/api-tokens
  • DELETE /api/v1/users/<USER_ID>/api-tokens/<TOKEN_ID>

Token creation and revocation (including admin revocation) are audited; the audit record contains the token name, scope, and hint — never the secret.