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:
npm run org:key:create -- --org acme --label "acme, hosted APIs" --scope platformThe 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:
npm run org:key:revoke -- 12 --reason "rotated"Using it
The same key, at each service's own host:
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 and 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:
POST /api/v1/keys/verifyThe 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:
npm run service:token:create -- --service searchThe 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:
POST /api/v1/receiptsIt 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.
