Trappr
Docs/Security/Key Management

Key Management

Trappr uses several distinct key types, each with a specific scope and lifetime. Understanding the key hierarchy helps you deploy agents securely and limit blast radius if a key is ever compromised.

Key types

Key typePrefixUsed for
User API keycht_Authenticates requests to the Trappr management API (dashboard actions, agent registration)
Gateway Access Keycht_gw_Scoped key your agent uses to route LLM calls through the Trappr Gateway
Agent API keycht_ak_Identifies a specific registered agent; used for execution tracking and heartbeats
Execution tokenchtx_Short-lived token scoped to one execution; attached to gateway calls to group them

How provider keys are stored

When you add a LLM provider key (OpenAI, Anthropic, etc.) in Settings → Providers, Trappr encrypts it at rest using AES-256-GCM before storing it in the database. The key is never logged, never returned via the API after creation, and never exposed to your agents.

When the gateway forwards a request to your provider, it decrypts the key in memory, uses it for the outbound call, and discards it — it is never written to disk or logs in plaintext.

Your LLM provider API key and your Trappr Gateway key are completely separate credentials. Agents never see your provider key — they only know the gateway key.

Gateway key scoping

Gateway keys can be restricted to:

  • Specific models — whitelist which models this key can request
  • Specific provider — route to OpenAI only, Anthropic only, etc.
  • Enforcement mode — MONITOR or ENFORCE applied to all calls with this key

If an agent sends a request for a model not on the allowlist, the gateway rejects it (in ENFORCE mode) or logs it (in MONITOR mode).

Rotating keys

To rotate a gateway key or agent key:

1
Create a new key

In the Trappr dashboard, generate a new key with the same settings as the existing one.

2
Update your agent

Deploy the new key to your agent. Both the old and new keys work during the transition window.

3
Revoke the old key

Once all agents are using the new key, revoke the old one from the dashboard. Requests using the revoked key are immediately rejected.

Revoking a key takes effect immediately. Make sure your agent is fully deployed with the new key before revoking the old one to avoid service interruption.

What to do if a key is compromised

If you suspect a gateway key or agent key has been exposed:

  1. Go to Dashboard → Gateway → Access Keys
  2. Click Revoke on the compromised key — it is immediately invalidated
  3. Review Gateway → Logs for any requests using that key that you didn't authorize
  4. Create a new key and redeploy your agent
← PreviousZero-Trust ModelNext →Data Handling