Apps & authentication

Most application requests involve two kinds of credentials:

• An App API key (an nvoken API key) lets your backend call nvoken for one App.
• A provider key pays Anthropic, OpenAI, Google, or xAI for model calls.

They are not interchangeable. Send the App API key as the bearer token for the hosted API. Store provider keys in the nvoken dashboard or supply one for a single Turn.

The CLI can save an App key after you approve a browser login and choose the App it may access. Browser access and signed outbound deliveries use narrower, purpose-built credentials. Those paths are covered later on this page.

Create an App in the dashboard

Sign in at nvoken.com and create an App. The App is the outer boundary for Agents, Conversations, MemorySpaces, Turns, API keys, provider keys, and usage. One App cannot read another App's data.

Use separate Apps when two products or environments should have separate keys and runtime data. Within an App, use tenant_key to partition customer data.

Issue an API key

Open API keys inside the App. The page shows the API base URL and lets you issue two kinds of key:

Every key is confined to one App. You can also give it an expiry time.

The secret appears once. Copy it into your secret manager before closing the dialog. nvoken stores a verifier, not the bearer secret. If a key is exposed, revoke it from the dashboard and issue another one.

Send the key with every API request:

Authorization: Bearer nvk_…

For an App key, GET /v1/identity returns its App and credential type. It is a useful first request when authentication or scope looks wrong.

Sign the CLI in through the console

Install the command-line client, then start the browser-assisted login:

go install github.com/deepnoodle-ai/nvoken/cmd/nvoken@v0.32.0
nvoken auth login

The CLI prints a short device code and approval URL, and opens the URL when it can. During approval, choose one App and either an App key or a read-only App key. The CLI saves that 90-day key and shows which App it belongs to. Use an App key in trusted application code; choose the read-only type when the CLI only needs inspection access.

For a remote or headless shell, add --no-browser and open the printed URL on another device. A self-hosted console can be selected with --console-url or NVOKEN_CONSOLE_URL. For CI, set NVOKEN_API_KEY or pass --api-key; the CLI verifies and saves that key without opening a browser.

The command-line client guide also covers the Homebrew install, named profiles, JSON output, and request files.

Store a provider key

Open Provider keys inside the App. Provider keys can be scoped to the whole App or to one tenant partition.

An App-scoped key is the simple default. When a Turn does not set provider_keys, nvoken uses the stored App key for that model provider.

A tenant-scoped key must be selected deliberately by a Turn carrying the same tenant_key. nvoken does not guess which customer should pay.

Provider secrets are encrypted before storage. The dashboard sends the secret once and cannot read it back. You can rotate or revoke the stored key without changing your application code.

Supply a key for one turn

Use caller_ephemeral when you do not want to store a provider key for reuse. The key travels with one Turn, is encrypted so accepted work can recover, and is cleared after the Turn settles.

The other public selections are app_byok and tenant_byok. A selected source is part of the accepted turn: nvoken never falls through to a different payer after it starts.

A provider key answers exactly one question — whose model account pays for this turn. It is not a place to keep the credentials your agent's own tools need; those stay with the tools, in your application.

Credentials a browser may hold

Never put an nvoken API key in browser code. An App key can do everything your backend can do inside its App, and a page that ships one has handed that to everybody.

When a browser needs to reach nvoken directly, it holds one of two narrower things instead:

• A client token — a short-lived EdDSA JWT your backend mints, signed by an Ed25519 key registered with the App. It pins exact tenant, user, Agent revision, Conversation, MemorySpace, tool, and limit constraints.
• An anonymous token — issued by nvoken itself to a visitor with no account, for Apps that enable it, only from an allowlisted origin.

Both are constrained well below any machine credential: no Conversation deletion, no hard cancel, no credential, provider-key, usage, App, or Org operations. See Browser access.

Signing keys, and rotating them

nvoken signs what it sends you. Callback deliveries and webhooks each carry X-Nvoken-Signing-Key-Id and X-Nvoken-Signing-Key-Version, and your receiver selects a secret from that pair before verifying the raw body — see Tools for the callback signature itself.

The key ID names the App and the purpose (callback or webhook) and does not change across versions. The version selects the secret inside it. Key material is delivered exactly once, at mint, and can never be read back.

Rotation is a sequence, not a swap, and the order matters because a receiver's rejection is not retryable — a 401 settles the call as a delivery failure rather than re-arming it.

1. Mint version n+1. nvoken keeps signing with version n.
2. Add the new secret to your verifier beside the old one. You already select by key ID and version, so holding two entries is configuration, not new code.
3. Activate the new version, once your receiver verifies against it. This takes effect on the next delivery; there is no cache anywhere.
4. Retire the old version.

Done in that order, no delivery ever fails verification. A purpose holds at most two versions at a time, so a third mint is refused until you retire one — no receiver could tell three apart. Retiring the version that is currently signing is refused, so a mistaken retire fails loudly instead of silencing every delivery your App makes. Nothing expires on a timer.

Rotation runs from the nvoken dashboard. The console performs these operations with its installation authority; an App key cannot provision signing keys or grant itself more authority.

Narrow machine access to one tenant or end user

Your application still decides who the end user is and what product actions they may take. Pass that decision explicitly with every facade call:

const agent = await client.agent("support");
const result = await agent.run("Help with this request.", {
  tenant: "acme",
  user: "user-481",
});

Exact raw calls send X-Nvoken-Tenant-Key and, when present, X-Nvoken-User-Key. Anything outside that scope is reported as not_found, including a real ID copied from another customer. A user assertion always requires its tenant assertion.

Check end-user permissions before calling nvoken or executing a host tool. nvoken knows which App and tenant a turn belongs to; it does not know whether a particular person may issue a refund, send an email, or read a customer record.