proxykey documentation

Overview

You give proxykey a real provider key once. It is encrypted and never leaves the server. In return you issue passes (tokens starting with vlt_) and hand those to your apps, scripts, or AI agents. Each request goes to proxykey instead of the provider; proxykey validates the pass, injects the real key on its side, and forwards the call.

• The client never holds the real key — only a pass you can revoke in one click.
• Per-pass control — rate limits, IP binding, expiry, and request logging.
• Any HTTP provider — OpenAI-compatible LLMs, Anthropic, Telegram, or any custom REST API.

How it works

Three objects, in a chain:

# the request path
client  ──(vlt_ pass)──▶  api.proxykey.org  ──(real key)──▶  provider
                              │
                    validate pass, inject
                    real key, forward, stream back

The real key is decrypted in memory for the single request only. It is never logged, cached in plaintext, or sent back to the client.

Quick start

# before — talking directly to OpenAI
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer sk-...realkey..."

# after — through proxykey
curl https://api.proxykey.org/p/openai/v1/models \
  -H "Authorization: Bearer vlt_openai_..."

The proxy endpoint

Send every request to the proxy host, keeping the provider's original path:

https://api.proxykey.org/p/<provider_slug>/<original_path>

# only the host changes — the path stays
https://api.openai.com/v1/chat/completions     → https://api.proxykey.org/p/openai/v1/chat/completions
https://api.groq.com/openai/v1/chat/completions → https://api.proxykey.org/p/groq/openai/v1/chat/completions

• <provider_slug> selects the upstream (see Providers).
• Everything after the slug is appended to the provider's real base URL. If that base already contains a version prefix (e.g. Hubris' /v1), do not repeat it.
• Your HTTP method, request body, query string, and non-auth headers pass through unchanged. Responses (including streamed SSE) are returned verbatim.

curl -s -o /dev/null -w "%{http_code}\n" \
  https://api.proxykey.org/p/openai/v1/models
# => 401  (route is up; 401 = no valid pass supplied)

Authentication

A request carries its pass in one of three ways. proxykey checks them in this order:

1. Authorization header — Authorization: Bearer vlt_… (recommended for most providers).
2. X-Vault-Pass header — X-Vault-Pass: vlt_… (when you cannot set Authorization).
3. In the URL path — for providers that natively carry the credential in the path (Telegram). Put the pass where the real token used to go; proxykey extracts it, strips that segment, and injects the real key. See Recipes → Telegram.

Providers & slugs

Each provider defines its upstream and how proxykey attaches the real key. The live catalogue is also returned by the MCP tool list_providers (note: it reports each provider's original base URL, not the proxy address — the proxy address is always …/p/<slug>/).

Auth models

Recipes

OpenAI-compatible (openai, openrouter, groq, together, mistral, deepseek, …)

Take the base URL you already use and swap the host for …/p/<slug> — keep the rest, including /v1. Use the pass as the API key.

# python openai SDK — the host is the only change
client = OpenAI(
  base_url="https://api.proxykey.org/p/openai/v1",   # was https://api.openai.com/v1
  api_key="vlt_openai_...",
)

# same idea for the others — keep each provider's own path
#   groq       → …/p/groq/openai/v1
#   openrouter → …/p/openrouter/api/v1
#   together   → …/p/together/v1
#   mistral    → …/p/mistral/v1
#   deepseek   → …/p/deepseek

Providers whose base already includes /v1 (e.g. hubris) accept both shapes: the proxy collapses a duplicated /v1 boundary, so …/p/hubris/v1/chat/completions and …/p/hubris/chat/completions hit the same upstream.

Anthropic

POST https://api.proxykey.org/p/anthropic/v1/messages
     Authorization: Bearer vlt_anthropic_...
# proxykey injects the real key as the x-api-key header upstream

Telegram

Telegram carries its token in the URL path. You do not restructure anything — keep your URL shape, change only the host, and put the pass where the bot token used to go.

https://api.telegram.org/bot<TOKEN>/sendMessage

# becomes — change host + use the pass instead of the token

https://api.proxykey.org/p/telegram-bot/bot<vlt_telegrambot_...>/sendMessage

No header, no path rewrite. Most Telegram SDKs let you set the API base host and the bot token — that is all you change (host → …/p/telegram-bot, token → your vlt_ pass). Alternative: drop the /bot<…> segment and send the pass in Authorization: Bearer against …/p/telegram-bot/sendMessage. Both work.

Telegram libraries (aiogram, telebot, grammY)

These libraries validate the token format <digits>:<hash> before the first request — a bare vlt_… pass fails their check. Prefix the pass with your bot id and a colon; the proxy accepts the composite form and ignores the digits:

# aiogram 3.x — two changes, zero client-code hacks
from aiogram import Bot
from aiogram.client.session.aiohttp import AiohttpSession
from aiogram.client.telegram import TelegramAPIServer

session = AiohttpSession(
    api=TelegramAPIServer.from_base("https://api.proxykey.org/p/telegram-bot")
)
bot = Bot(token="8759668576:vlt_telegrambot_...", session=session)
#            ^ your bot id + ':' + the pass — passes the library's format check

File downloads work through the same host: …/p/telegram-bot/file/bot<token>/<file_path> is proxied to Telegram's /file/bot<real>/…. Long polling (getUpdates?timeout=50) is safe — the proxy's upstream budget is 300s.

generic-rest (any custom API)

Configure the secret with a custom base URL and auth model. Then call:

https://api.proxykey.org/p/generic-rest/<your path>
     Authorization: Bearer vlt_genericrest_...

Passes

A pass is a revocable token bound to one secret. You can issue many passes per secret (one per app, per agent, per environment) and control each independently.

Lifecycle

• Rotate — mint a fresh token with the same settings; the old token stops working immediately.
• Revoke — disable the pass at once (proxy cache invalidated). Further requests get 401 pass_revoked.
• Rebind IP — clear the learned IP so the next request re-binds.

The full vlt_… token is shown only once, at creation or rotation. proxykey stores only its hash and can never display it again.

Pending passes

An AI agent can issue a pass before the real key exists, so it never has to touch the key itself. Such a pass starts in status pending_secret and is blocked — the proxy returns 409 original_key_required — until a human supplies the real key.

MCP for AI agents

proxykey ships a hosted Model Context Protocol server so an AI agent can manage passes on your behalf — without ever seeing a real key.

Connect

Issue an MCP token (mcp_…) in the panel, then point your client at the hosted Streamable-HTTP endpoint:

URL:   https://mcp.proxykey.org/mcp
Auth:  Authorization: Bearer mcp_...

The panel's MCP → Quick Connect gives ready snippets for Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Cline, and Codex CLI.

Tools

An MCP token is scoped to pass management only:

• list_providers, list_secrets — catalogue & secret metadata (never values)
• create_pass, create_pending_pass — issue passes
• update_pass, rotate_pass, revoke_pass, rebind_pass_ip — manage them
• get_pass_stats, get_pass_logs — usage & audit
• get_manual_secret_setup — returns the panel URL where a human enters a real key

Security model

• Envelope encryption. Every secret is sealed with AES-256-GCM under a per-secret data key, which is itself wrapped by a master key. The secret's identity is bound into the encryption (AAD), so ciphertext cannot be moved between records.
• Keys never leave. A real key is decrypted in memory for one request and dropped. It is never returned by any API, cached in plaintext, or written to logs.
• Log redaction. Request logs store method, path (without query), status, latency and byte counts. Pass tokens, bearer tokens, and key-like strings are redacted from any stored body preview.
• SSRF guard. Custom upstreams are resolved and blocked if they point at private, loopback, or cloud-metadata addresses.
• Per-pass containment. A leaked pass is rate-limited, optionally IP-bound, individually revocable, and never exposes the underlying key.

Errors

Errors are JSON: { "error": "<code>" }. No internal detail is leaked.

Any other status is the upstream provider's own response, passed through unchanged.

Cheat sheet

Proxy     https://api.proxykey.org/p/<slug>/<path>
Auth      Authorization: Bearer vlt_...   (or X-Vault-Pass, or in-path for Telegram)
Panel     https://app.proxykey.org
MCP       https://mcp.proxykey.org/mcp    (Bearer mcp_...)

Rule          replace your provider's scheme+host with  …/p/<slug>  — keep the rest of the path
OpenAI        base_url = …/p/openai/v1       key = vlt_openai_...
OpenAI-style  openrouter · groq · together · mistral · deepseek   (keep each one's own path)
Anthropic     …/p/anthropic/v1/messages     Authorization: Bearer vlt_anthropic_...
Telegram      …/p/telegram-bot/bot<vlt_...>/sendMessage
Any LLM       slug openai-compatible  + base URL on the secret
Any REST      slug generic-rest       + base URL + auth type