Reference

Virtual keys

A virtual key is your app’s identity at the gateway. Provider keys stay inside the gateway; your app only ever holds its own key.

Early accessBy invitationLast updated 5 October 2026

One key per app

Every app gets its own key, so its spend, its limits and its model list are its own. With the policy layer an app gets one key per data class and lane, so a children’s request can never borrow a personal-data key.

Because apps call with their own gateway key, replacing a provider key is one change at the gateway, with no change to the apps that use it.

What a key carries

Limits come in tiers, from light apps to high-volume agent workloads, and are set when we issue the key. Behind the per-key limits, the gateway also caps spend per provider and overall, so one runaway app cannot drain a shared provider account.

The spend ledger

Every call is written to the ledger: which key, which alias, which model answered, the tokens in and out, and the cost. That gives cost per app from the first call.

• The ledger is configured not to store prompts or responses.
• Cost per customer, per user and per feature is not recorded at the gateway; the policy layer, now in staging, adds it.
• Each response also carries diagnostic headers: the alias that answered, how many fallbacks were tried, the cost of the call and the key’s spend so far. The header names come with your invitation.

Handling your key

• Keep it in a server-side secret store or environment variable. Never commit it, and never log it.
• Never ship it in a browser, mobile app or desktop installer. If users need AI features, call the gateway from your backend.
• Use separate keys for separate apps or lanes, rather than sharing one.
• If a key leaks, tell us through askshiva.in. We issue a new key with the same settings and retire the old one, which then answers 401.

At a limit