API keys

If you integrate Verbatim AI into your own systems, you call our secured API with JWT
tokens. You sign those tokens with your private key (which always stays on your
side), and we verify the signature with the matching RSA public key that you publish
here.

🔐

Only the public part of your key is ever published. Your private key must never

leave your side.

Your organisation Id 🆔

Signing a token is not quite enough: it also has to say which organization is calling. That
is your organization Id, carried in the oid claim of every JWT you mint.

You will find it on your profile — tap your avatar at the top-right, and it
sits just under your email as a chip. Tap the chip to copy it. 📋

Your keys at a glance 📇

You access your keys from your profile - Tap on Keys button at the bottom right of the page.

The key list shows every RSA public key published for your organization. Each key is a card
with its main details:

• Its name. By convention, the name of your key is identical to the key on your server (using the --key-name option in python-token-builder).
• its ID. The internal ID of your key, required for signing your tokens. See our guide
• Its description (if you added one)
• Its status — Active ✅ or Inactive ⏸️
• Its publication date

Tap a card to open the key detail. Pull the list down to refresh it at any time. 🔄

Publish a new key ➕

Open the full list of keys with Show more and tap its ➕ button — or, with no key
yet, Publish your first key on the key page — to publish a key:

1. Name (required) — identifies the key later (e.g. the service or environment that
   uses it).

2. Description (optional) — a few words on what the key is for; shown in the list and
   on the detail page.

3. Public key content — paste the PEM-encoded public key. It should look like:

   -----BEGIN PUBLIC KEY-----
   ...
   -----END PUBLIC KEY-----

Before publishing, we check that a name is filled and the content is a valid PEM public
key. Click Save to publish, or Cancel to leave without saving.

⚠️

Read our user guide to produce your RSA keys.

⚠️

A private key is always rejected — never paste a private key here.

ℹ️

Once published, the RSA content can never be read back or edited. You can still

rename the key, change its description, activate/deactivate it, or delete it.

Activate or deactivate a key 🔁

Each card has a switch to toggle the key without leaving the list:

• An active key can verify your JWT tokens.
• An inactive key is kept but is no longer used for verification.

ℹ️

A key must be deactivated before it can be deleted.

Get a fresh token 🎫

The Get a key button at the top of the page copies a fresh JWT token to your
clipboard — handy to quickly call the secured API. The token is verified with the public
keys you have activated.

Key detail

The detail page shows everything you can manage for a single key:

• Its description, format (PEM), creation date and last update
• A switch to activate / deactivate it
• The pencil icon ✏️ (top-right) to edit its name and description

🔐

For security, the RSA content is never displayed. A key can only be renamed,

described, activated, deactivated or deleted — never read back.

Edit a key ✏️

From the edit view you can change the name (required) and the description
(optional — leave it empty to remove it). The RSA content, format and activation status
cannot be changed here. Click Save to confirm, or Cancel to discard.

Delete a key 🗑️

The Delete this key button removes the key permanently. It is only available once the
key is deactivated — the button stays disabled while the key is active.

⚠️

Deletion is definitive. A deleted key can no longer verify JWT tokens and cannot be

restored. A confirmation is asked before it is applied.

Access tokens 🎟️

An RSA key lets your servers mint their own JWTs. An access token is the lighter
option: a short-lived, opaque token that Verbatim AI mints for you, carrying only the
permissions you pick. Hand one to a front-end, a widget or a script that should reach a
small part of the API for a little while — and nothing else.

Send it as the X-Access-Token header of your /v1/ API calls.

Access tokens are listed on the same page as your keys, in the Access tokens section
under them.

Your tokens at a glance 📇

Each row shows:

• the first characters of the token — enough to recognise it, never enough to use it,
• when it was created and when it expires (or expired),
• one colored chip per scope domain it carries (corpus, doc…) — tap it to see the
  actions the token is allowed there,
• the issuer, email and user id it was created with.

An expired token shows its value in red, behind a ⏱️ icon.

ℹ️

An expired token stays in the list until you revoke it, but it no longer

authenticates anything.

The key page shows your first 3 tokens; Show more under them opens the full list, which
loads more as you scroll down.

Create a token ➕

Open the full list of tokens with Show more and tap its ➕ button — or, with no
token yet, Create your first token on the key page:

1. Scopes (at least one) — what the token may do, grouped by part of the API. Each
   entry is DOMAIN:ACTION: read opens GET, create opens POST, and so on — hover an
   entry to see the HTTP methods it allows. Running a RAG query needs post:read.
2. Validity — 1 hour (default), 1 day, 1 month or 1 year. The token stops working
   once that delay has passed.

The token is stamped with the issuer console and with your own email and user id:
they are shown in the list, and are what GET /v1/auth/whoami answers for that token.

Click Create token. The full token is then shown once, with a button to copy it.

⚠️

Copy it before closing the dialog. It is the only time the full value is ever

shown: the list keeps only its first characters, and nothing can display it again. Lost
it? Revoke it and create a new one.

Revoke a token 🚫

Open the ⋮ menu of a row and choose Revoke. A confirmation is asked first.

⚠️

Revocation is immediate and definitive. Every request carrying the token is

refused from then on, and a revoked token cannot be restored.