Keys¶
Provider keys pasted into apps are shared, never rotated and impossible to trace. With Vidai, a program holds one Vidai key instead. The provider keys stay with the gateway. The Vidai key says whose calls these are, which team pays, which models it may call, how fast and until when. Rotate it, suspend it or hand it over without touching anything else.
What a key is¶
The thing a program holds to call models through the gateway. It goes where your SDK expects an API key; the gateway checks it on every call and uses its own provider credentials to reach the provider.
A key carries:
| Part | What it decides |
|---|---|
| Held by | A person, or an agent |
| Acts for | A person's key: one of their teams. An agent's key: the agent, and optionally one of its applications. This decides who pays |
| Environment | Where it lives, and so who may issue it and how long it may last |
| Models | Every model its team or agent may call, or only some |
| Rate limit | Requests a minute, its own or the default for its kind of key |
| Expiry | A day it stops, within the environment's longest key life |
| Translation | How the gateway translates between API formats for it |
Everything else that applies to a key (budgets, guardrails, routing, regions) is set at a level above it and reaches it from there. Its page lists the exceptions it has and what guardrails reach it: Checked by guardrails, Guardrails only log, or No guardrail reaches it.
flowchart LR
APP["Your program"] -- "Vidai key" --> GW["Gateway"]
GW -- "checks: key, model,<br/>rate limit, rules" --> GW
GW -- "provider's own key" --> PR["Provider"]
Rotating without an outage¶
Replace secret gives a key a new secret while the old one keeps working for a grace period you choose (no time, an hour, a day, three days or seven, within what your organisation allows), so callers can switch over. The key itself keeps everything: its models, rate limit, routing, exemptions, guardrails and budgets belong to the key, not the secret. While the old secret works the key says until when, and when it was last used, so you know when to choose Stop old secret now. After a leak, choose No time: the old secret is refused at once.

Why a key can stop working¶
A key stops at once, and works again when the reason goes. Its caller gets a refusal that says the key is off, with a short reason:
- suspended by hand;
- its person disabled, deleted, or no longer in the team it acts for;
- its agent suspended, or no longer in the application it acts for;
- past its expiry date (Vidai revokes it);
- a budget covering it was reached ("Stopped by Team cap until 1 Dec 2026");
- unused for your organisation's dormant-key period, when that's switched on.
Home lists keys that expire soon, have expired, are suspended or can call nothing, each with who holds it.
When someone leaves¶
Hand over… gives a key to another person or agent, with a new secret (recommended) or the same one, and a reason for the audit log, so whatever runs on it keeps running. When whoever issued a key can no longer issue it, the key keeps working and its team's admins can Take over.
What you see¶
Keys shows everyone their own keys (My keys), and admins and owners everything they look after. Above the list,
Connect your app gives the gateway's address and the SDK settings to copy. A key's secret is shown once, when it's
issued; lists show only how it starts (vk_abcd…wxyz). Last used comes from the gateway's own record of calls.


Keys and tokens are different things¶
A key calls models through the gateway. An API token manages Vidai itself (people, keys, rules) from a script. They never stand in for each other. See Service accounts and API tokens.
Related¶
- Environments · Applications and agents
- Model access: what a key may call
- Rate limits · Budgets
- Translation between API formats
- Request logs and the call record: a key's calls