How do I create an API token?

Requires Basic

Short answer

Open Administration → API Tokens, click “Create token”, give it a name (e.g., “CI Pipeline”), choose the scopes (read, write, or both), and optionally an expiration date. After saving, Notory shows the token value (inv_…) exactly once — copy it to a safe place right away. After that, only the prefix remains visible.

Prerequisites

Available on all plans.

Open API Tokens. Administration → API Tokens (“Personal access tokens for the REST API. The value is shown only once.”). The list shows Name, Prefix, Scopes, Created, and Last used.

Screenshot pending admin-api-tokens-01 API token management with a token list and 'Create token' button

The token list shows only metadata — never the secret value.
Create a token. Click “Create token”, give it a descriptive name (e.g., “CI Pipeline”), and choose the scopes: read (read only), write (read + write) — with no selection, full access within your role applies. Optionally set an expiration date.
Copy the value immediately. After creation you’ll see: “New token – copy it now, it will not be shown again:”. Copy the value (inv_…) into your password manager or your pipeline’s secret management.

Screenshot pending admin-api-tokens-02 One-time display of the newly created token with the inv_ prefix and a copy prompt

The plaintext value appears exactly once — after that, only the prefix remains visible.

Test it. A first call with the new token:

curl -H "Authorization: Bearer inv_dein_neuer_token" \
  https://demo.notory.io/api/v1/assets

Tokens themselves can also be managed via the API (e.g., using an existing browser session or an old token):

curl -X POST https://demo.notory.io/api/v1/api-tokens \
  -H "Authorization: Bearer inv_bestehender_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI-Pipeline",
    "scopes": "read,write",
    "expires_at": "2027-01-01T00:00:00Z"
  }'

The response (201 Created) contains the token field — only this one time:

{
  "id": "018f9e33-4d5e-7f66-a071-8b9c0d1e2f30",
  "tenant_id": "3d9b0c12-4e5a-4f88-b1c7-2a9e6d4f0011",
  "user_id": "b7c3d9e1-…",
  "name": "CI-Pipeline",
  "prefix": "inv_9f3kX2mQ",
  "scopes": "read,write",
  "expires_at": "2027-01-01T00:00:00Z",
  "last_used_at": null,
  "is_active": true,
  "created_at": "2026-07-08T10:31:07Z",
  "token": "inv_9f3kX2mQ7Lw…-vollstaendiger-wert-nur-jetzt"
}

List your tokens with GET /api/v1/api-tokens (no secret values, only metadata including prefix and last_used_at).

Possible errors: 401 (not signed in), 422 (unknown scope — only read and write are allowed; empty name).

What happens behind the scenes?

Secure format, hashed storage. Notory generates inv_ plus 32 random, URL-safe bytes. Only the SHA-256 hash is stored — the plaintext no longer exists server-side after the response. That’s why it can never be shown again. For recognition, Notory remembers the first 12 characters as the prefix.
Scope semantics. read allows only read methods (GET/HEAD/OPTIONS); write allows changes and includes read access. Without scopes, full access within your role applies (compatibility behavior). A mismatched access attempt ends with 403 (“API token scope does not permit this operation”).
Token ≤ user. Every request made with the token runs under your account: role, permissions, and tenant apply unchanged; tenant isolation (RLS) is set per request to the token’s tenant. If your account is deactivated, all your tokens become immediately useless (401).
Expiration and usage trail. After expires_at, the API responds with 401 (“Invalid or expired API token”). On every use, Notory updates last_used_at — so you can spot orphaned or misused tokens.