Skip to content

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.

A key's panel during a rotation: Old secret works until, and when the old secret was last used

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: Everything I look after, with each key's holder, what it acts for, environment, status and last use

Connect your app: the gateway's address and SDK settings for the OpenAI, Anthropic and Gemini SDKs

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.