> Source: https://vitna.ai/docs/one-key
> Raw Markdown: https://vitna.ai/docs/one-key.md
> Corpus index: https://vitna.ai/llms.txt
# One key for the hosted APIs
An org holds one key for Vitna's hosted APIs. Search, the Web APIs and the
Unblocker each accept it as `Authorization: Bearer vitna_key_...`, and each
checks it with vitna.ai, where the key lives as a hash beside the org's other
keys. During the beta an operator mints it.
## What it is
Every org key in the record holds exactly one scope, and a platform key holds
the third:
| Scope | Prefix | What it may do |
|---|---|---|
| `push` | `vitna_push_` | Post a runtime's closed days to `POST /api/v1/usage` |
| `router` | `vitna_push_` | Call the hosted router, which spends money at a provider |
| `platform` | `vitna_key_` | Call Search, the Web APIs and the Unblocker |
A platform key cannot push a ledger or call the router, and a push or router
key is not a platform key, so a key leaked out of one pipeline can do only
the one thing it was minted for. With it, the org is the service's client,
written `org.<id>`, and is limited and metered exactly as any other client of
that service is.
The keys each service issued before this, `vitna_search_`, `vitna_web_` and
`vitna_unblock_`, keep working, and a service tries its own keys first.
## Getting one
An operator mints it for the org, at a prompt, and it is shown once:
```bash
npm run org:key:create -- --org acme --label "acme, hosted APIs" --scope platform
```
The record keeps its sha256, never the key. The console lists every key an org
holds with what each may do; it does not mint or revoke them. Revoking is the
same command as for any org key, and a service stops accepting the key within
a minute:
```bash
npm run org:key:revoke -- 12 --reason "rotated"
```
## Using it
The same key, at each service's own host:
```bash
curl https://search.vitna.ai/v1/search \
-H "Authorization: Bearer $VITNA_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"solar system","mode":"index","maxResults":5}'
curl https://web.vitna.ai/v1/read \
-H "Authorization: Bearer $VITNA_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/","format":"markdown"}'
```
The playgrounds on [vitna.ai/search](https://vitna.ai/search) and
[vitna.ai/apis](https://vitna.ai/apis) take it too, in the field that asks for
that product's key.
## How a service checks it
A service asks vitna.ai, authenticated by a service token of its own, and
sends the key's sha256 rather than the key:
```text
POST /api/v1/keys/verify
```
The body is `{"key": "<sha256, lowercase hex>"}` and nothing else. The answer
is `{"active": true, "key": {"id": "12", "org": "acme"}}` for a live platform
key, and `{"active": false}` for anything else: an unknown key, a revoked one,
or a key of another scope, which are not told apart. A service token that is
not configured is refused before any lookup, and an instance that cannot read
the record answers `503` rather than calling the key inactive.
A service keeps a live answer for a minute and a refusal for thirty seconds,
so a revocation lands within a minute. When vitna.ai cannot answer, a key the
service saw live within the last six hours stays live, and a key it has never
seen is answered `503` with `retry-after`, never `401`, because "I could not
look" is not "you may not". Lookups of keys a service has not seen are capped
per minute, so a flood of made-up keys at a service is not a flood at
vitna.ai.
## Setting a service up
Mint the service's token, which prints both halves:
```bash
npm run service:token:create -- --service search
```
The token and the endpoint go in the service's own environment, as
`VITNA_PLATFORM_SERVICE_TOKEN` and `VITNA_PLATFORM_VERIFY_URL`; the line it
prints goes in the site's `VITNA_KEY_VERIFIERS`, a JSON object of service name
to token hash. A service with neither variable set does not accept platform
keys, and one with only one of them refuses to start.
## What the console sees of a request
Every request a service admits gets a receipt: its request id, the client,
when it started, how long it took, its status or outcome, and the providers or
routes it tried. A receipt never carries the query, the page or the answer.
Since 2026-10-11 a service that accepts platform keys also sends the receipts
for an org's requests to vitna.ai, where the console's Activity lists them,
newest first, each one open to inspect:
```text
POST /api/v1/receipts
```
It is authenticated by the same service token as key verification, and it
names no service in the body: the token says which service is posting. The
body is `{"receipts": [ ... ]}`, at most 500 at a time. Each receipt is read
through an allowlist, so a field the console has no column for never reaches
the record, and a receipt whose client is not `org.<id>` is dropped. A request
reported twice is one row.
Each receipt is filed under the console product it belongs to as it lands:
Search, the Unblocker, the Browser (the Web APIs' `browser` sessions) or Web
extraction (the Web APIs' read, scrape, extract, map, crawl, screenshot, pdf,
documents, product, company, research, catalog, careers and search operations). A
receipt that belongs to none of them is dropped and the answer says why:
reading or cancelling a job, whose own receipt arrives when the job ends,
and the recipe, monitor, dataset, published, sources, firehose and session
routes, which the console has no page for yet. A page of a SERP collection
job is recorded under its job's id and page number, since it has no request
id of its own. A service whose name is not `search`, `unblocker` or `web` is
refused whole with 403, so a verifier added under a new name shows up in the
site's journal on its first batch rather than as rows no page shows.
A Browser session that ended the way its client asked, by `browser.close()`
or by closing its socket, reads as ok whatever close reason the client sent;
one the service ended (shutdown, a protocol error, the session, idle or
transfer limit) reads as failed.
A service sends them in the background, in batches every few seconds, and a
request never waits on it. If vitna.ai cannot take a batch, the batch waits
and is retried, doubling its wait up to five minutes; past 5,000 queued
receipts the oldest are dropped first. A 401 or 403, which means the
service's token or its name is not configured on vitna.ai, is retried the
same way, because fixing the setting should not lose what was queued; only a
batch refused for what it is (400 or 413) is not sent again. The address is
`/api/v1/receipts` on the host `VITNA_PLATFORM_VERIFY_URL` names, so
releasing a service with this change is what turns it on.
`VITNA_PLATFORM_RECEIPTS_URL` points it elsewhere and
`VITNA_PLATFORM_RECEIPTS=off` keeps it off.
vitna.ai's own Search relay, which vitna.ai/search and the console's Search
workspace both use, records the searches it carries for an org's key as
well, so a search run from the console is in Activity the moment it finishes.
The console's Unblocker workspace sends through vitna.ai's Unblocker relay,
which records nothing itself, so its runs are in Activity once the service's
next batch lands, a few seconds later.
The query and the results of a run made in the console are kept only in the
browser that ran it, which is how the inspector can show them beside the
record without vitna.ai ever holding them. Of an Unblocker run that copy keeps
the page's text up to 20,000 characters, its first hundred links and every
attempt, and never the HTML. They are kept for the account that
ran them, another account signed in to the same browser never sees them, and
signing out from the console forgets them, together with the org key pasted
into the workspace.
## What it does not do yet
- **Self-service keys.** The console names keys and their scopes and does not
mint them. Letting the web process mint and revoke is a decision of its own,
since today no role it holds can write a key.
- **One statement across products.** Each service meters an org's use on its
own; nothing yet totals them. Since 2026-10-16 the console's Plan page counts
the Unblocker's delivered pages per org and UTC month from these receipts,
the unit its proposed price names, and prints a count, never a price. The
receipts are sent best effort (a service past 5,000 queued drops the oldest),
so that count is not yet a ledger a statement can be billed from.
- **A trace across products.** Each service mints its own request id, so a
search followed by a page read and a model call are three unrelated rows in
Activity. Joining them needs a trace id every service carries forward.
- **Retention.** Nothing prunes the receipts the console reads yet.