How do Cognocient proxy keys work?

Cognocient proxy keys are how your application authenticates with the proxy. One key per environment, per team, or per product — scoped to exactly what each caller needs.

Cognocient proxy keys (sk-cog-...) replace your provider API keys in your application. One key per environment or team — your real provider keys are stored encrypted server-side and never exposed in logs or API responses.

Key architecture

Your Cognocient proxy key replaces the AI provider API key in your application. Cognocient holds your actual provider keys in a vault — they never appear in your codebase or environment variables.

# Before (provider key in environment)
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxx

# After (Cognocient proxy key — scoped, rotatable, auditable)
OPENAI_API_KEY=sk-cog-prod-support-xxxxxxxx
           ↑   ↑    ↑       ↑
           cog prefix  environment  team/feature scope  unique ID

Feature	Description
No provider key exposure	Your OpenAI / Anthropic keys are stored encrypted in Cognocient's vault. A leaked proxy key cannot be used to call providers directly.
Instant rotation	Rotate any key from the dashboard in one click. The old key is invalidated immediately — no coordination with providers required.
Per-key spend visibility	Every call is attributed to the key that made it. Filter Live Calls by key to see exactly what a specific environment or team is spending.

Creating and scoping a key

Go to Control → API Keys → New Key. Each key has the following settings:

Name — Human-readable label, e.g., "Production — Customer Support" or "Staging — Engineering." This appears in the Live Calls view and spend reports.

Allowed providers — Restrict this key to specific providers (e.g., OpenAI only). Calls to other providers will be rejected with a 403. Useful for environment keys where you know exactly which providers are used.

Allowed models — Optional whitelist of models this key can call. Use this to prevent a feature team from accidentally calling an expensive model not in their budget.

Monthly spend cap — Hard spend limit for this key in a billing cycle. When reached, all calls return 429. Pair with a second key for failover if you need resilience.

Default attribution headers — Pre-fill X-Cost-Department and X-Cost-Team on every call made with this key, even if the application doesn't send the headers. Useful for ensuring legacy code is attributed correctly without a code change.

Best practices for key management

One key per environment — Create separate keys for production, staging, and development. This prevents staging traffic from inflating your production cost reports and lets you set different spend caps per environment.

One key per team (on Business plan) — If multiple teams access the proxy, give each team its own key. Spend is then naturally segmented by team in your dashboard without requiring every developer to set attribution headers.

Store keys in environment variables only — Never hardcode proxy keys in source code. Use .env files locally and your secret manager (AWS Secrets Manager, GCP Secret Manager, Doppler) in production.

Rotate keys quarterly — Use the one-click rotation feature every 90 days. After rotating, update the secret in your secret manager — the old key is immediately invalidated.

Set a spend cap on every key — A leaked key with no spend cap is a billing risk. Even for production keys, set a cap at 150% of your normal monthly spend as a backstop.

Using a proxy key in your code

from openai import OpenAI
 
# Replace your provider key with the Cognocient proxy key
# The base_url points to the Cognocient proxy instead of OpenAI
client = OpenAI(
    api_key="sk-cog-prod-support-xxxxxxxx",  # your Cognocient key
    base_url="https://api.cognocient.com/v1",
)
 
# Everything else stays exactly the same
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
    extra_headers={
        "X-Cost-Feature": "support-chat",
        "X-Cost-Department": "customer-success",
    },
)

If you have set default attribution headers on the key, you don't need to send them per-call. The proxy merges the key defaults with any per-call headers, with per-call headers taking precedence.

Next steps: Data Security · Budget Enforcement · Attribution Headers

Key architecture

Creating and scoping a key

Best practices for key management

Using a proxy key in your code

On this page