AI Gateway Virtual Keys

A Virtual Key is a credential issued by the AI Gateway for accessing the gateway's proxy endpoints. You hand out Virtual Keys to your apps and AI tools, while the real provider API keys stay only on the gateway side. This avoids scattering real keys everywhere while letting you individually scope, rate-limit, rotate, and revoke each Virtual Key. This article covers the full lifecycle management of Virtual Keys.

Why Use Virtual Keys

• Protect real keys — Apps and tools only ever touch Virtual Keys; the provider's real key is never exposed.
• Scope permissions by purpose — Create different Virtual Keys for different projects or tools, each with its own allowed models, allowed channels, and rate limits.
• Revoke at any time — If a key leaks or is no longer needed, just revoke or rotate it without affecting other keys.

Prerequisites

• You are signed in to your ServBay account.
• You have added at least one usable channel on the Channels page.

Creating a Virtual Key

Go to the AI Gateway → Keys page and click Create:

• Name — Identifies what the key is used for (e.g., claude-code, my-app-dev).
• Description (optional) — Additional notes.
• Expiration — Set to never expire or to a specific date.
• Allowed channels (optional) — Use tag multi-select to restrict the key to routing only to specified channels; leave empty for no restriction.
• Allowed models (optional) — Restrict the key to calling only specified models; leave empty for no restriction.
• Rate limits (optional):
  • RPM / TPM — Maximum requests / tokens per minute.
  • RPD / TPD — Maximum requests / tokens per day.

The plaintext can be retrieved at any time

Once a key is created, the gateway displays the plaintext key (in the form servbay-sk-xxxxxxxx...). The gateway stores the plaintext locally, so you can still retrieve it later from the key details; only legacy keys created earlier via hashing have no recoverable plaintext (requesting it returns 409). If you suspect a key has leaked, simply use "Renew".

Key List

The key list shows, for each Virtual Key:

• Prefix — e.g., servbay-sk-abcd..., used for identification.
• Status — active, revoked, or expired.
• Created at / Last used at.
• Permission tags — Allowed models / channels and rate limits.

Managing Keys

In the key list, you can perform the following actions on each key:

Action	Description	Impact
Edit	Modify the name, description, allowed models / channels, and rate limits	Takes effect immediately; the key itself does not change
Renew	Regenerate the plaintext; the old plaintext becomes invalid immediately, and the new plaintext can be retrieved at any time	You must update every app and tool using this key
Revoke	Immediately deactivate the key while keeping the audit record	Irreversible; requests using this key will be rejected
Delete	Permanently delete the key	Irreversible

Renew vs. Revoke

• Renew: The key itself remains, only the plaintext changes — ideal when you suspect a key has leaked but still want to keep using the same key configuration. Remember to update the consumers accordingly.
• Revoke: Makes the key permanently invalid while keeping the record for auditing — ideal when you're sure a key is no longer needed. Both Renew and Revoke require a second confirmation.

Relationship with One-Click Takeover

When you use One-Click Takeover to point an AI tool at the gateway, the gateway automatically creates a dedicated Virtual Key for that tool and writes it into the tool's configuration. You can also manage these auto-created keys manually on the Keys page.

FAQ

• Q: What if I forgot to copy the plaintext key?
  • A: You can retrieve the plaintext from the key details. Only legacy keys created earlier via hashing cannot be retrieved — in that case, use "Renew".
• Q: What's the difference between Revoke and Delete?
  • A: Revoke keeps the key record (useful for auditing), while Delete removes it entirely. Both make the key invalid immediately.
• Q: After restricting "allowed models", what happens if an app requests other models?
  • A: The gateway rejects model requests outside the key's permissions. Make sure the models your app uses are in the allow list, or lift the restriction.
• Q: What happens when a rate limit is triggered?
  • A: Requests exceeding RPM/TPM/RPD/TPD are throttled by the gateway. You can check actual usage on the Statistics page and then adjust the limits.

Summary

Virtual Keys let you hand out AI capabilities to apps and tools with least privilege and revocability. Combined with allowed-model / allowed-channel restrictions and rate limits, you can tailor credentials for each use case and rotate or revoke them at any time — all without ever touching the real provider API key.