Getting started
Apps & authentication
Create an App at nvoken.com, issue a scoped API key, and choose which model-provider key pays for each turn.
nvoken uses two kinds of credentials:
- 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 nvoken API key as the bearer token for the hosted API. Store provider keys in the nvoken dashboard or supply one for a single Invocation.
Create an App in the dashboard
Sign in at nvoken.com and create an App. The App is the outer boundary for Sessions, Invocations, 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:
| Profile | Use it for |
|---|---|
Runtime | Create and control Invocations, read Sessions, use tools, and inspect models |
Viewer | Read non-secret runtime data for support or reporting |
You can constrain a key to one tenant_key and give it an expiry time. Those
settings only narrow the profile.
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_…GET /v1/identity returns the App, profile, and constraints attached to the
current key. It is a useful first request when authentication or scope looks
wrong.
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 an Invocation does not name a provider credential selection, nvoken uses the stored App key for that model provider.
A tenant-scoped key must be selected deliberately by an Invocation 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 Invocation, is encrypted so accepted work can recover,
and is cleared after the Invocation 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 admission.
Keep end-user authorization in your app
tenant_key is an isolation boundary inside an App. user_key is optional
metadata for filtering and attribution. It is not an authorization boundary.
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.