API Keys

Kadryn API keys authenticate server-side requests to Kadryn developer surfaces such as Gateway, direct ingest, diagnostics and automation workflows.

Use API keys to connect your backend, workers, ingestion jobs or internal platform services to Kadryn.

Never expose Kadryn API keys in browser JavaScript, mobile apps, public repositories, client logs or URLs.

What you will do

In this guide, you will:

1. create or rotate a workspace API key;
2. store the key safely in server-side environment variables;
3. use the key with Kadryn API and Gateway requests;
4. verify key usage in the Developers area;
5. understand rotation, permissions and production safety rules.

API keys vs provider keys

A Gateway request usually needs a Kadryn API key in the request and a provider key configured inside the workspace.

Create an API key

Open:

Developers → API Keys

Then select:

Create API key

If a key already exists, use:

Rotate API key

Kadryn shows the full secret only once. Copy it immediately and store it in your secret manager.

Kadryn continues to show safe metadata such as prefix, creation date and last used date, but it does not show the full secret again.

Store the key

KADRYN_API_KEY="kadryn_live_..."
KADRYN_API_BASE_URL="https://api.kadryn.com/v1"
KADRYN_GATEWAY_BASE_URL="https://gateway.kadryn.com/v1"

Store these values in server-side secret storage.

For local development, use a Git-ignored .env file.

Use with Gateway

curl "$KADRYN_GATEWAY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $KADRYN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Kadryn-Project: prod-api" \
  -H "X-Kadryn-Feature: support-agent" \
  -H "X-Kadryn-Environment: prod" \
  -d '{
    "model": "gpt-4.1-mini",
    "messages": [
      {
        "role": "user",
        "content": "Hello from Kadryn Gateway"
      }
    ]
  }'

Use with direct ingest

curl "$KADRYN_API_BASE_URL/usage/events" \
  -H "Authorization: Bearer $KADRYN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: usage-event-2026-07-06-001" \
  -d '{
    "timestamp": "2026-07-06T12:00:00.000Z",
    "provider": "openai",
    "model": "gpt-4.1-mini",
    "inputTokens": 1200,
    "outputTokens": 300,
    "costCents": "4",
    "project": "prod-api",
    "feature": "support-agent",
    "environment": "prod"
  }'

Key inventory

The API Keys page shows:

• key name;
• key prefix;
• environment;
• scopes;
• status;
• last used date;
• creation date.

Use the prefix to identify which deployed key is active without exposing the full secret.

Permissions

Only users with workspace management permissions can create or rotate API keys.

If you do not have permission, the page is read-only. You can inspect safe metadata, but you cannot generate or rotate the secret.

Rotation

Rotate an API key when:

• a key may have been exposed;
• a team member with access leaves;
• you move from test to production;
• regular secret hygiene requires it;
• old infrastructure still contains a key.

Before rotating, identify affected services:

• server environment variables;
• SDK workloads;
• Gateway authentication;
• direct ingest jobs;
• internal workers;
• CI/CD secrets.

After rotating:

1. copy the new secret;
2. update your secret manager;
3. redeploy affected workloads;
4. send a non-sensitive test request;
5. verify the new last-used timestamp;
6. remove old copies.

Security rules

Do:

• store keys server-side only;
• rotate keys regularly;
• restrict access to owners, admins and deployment systems;
• use idempotency keys for retryable writes;
• preserve traces for production debugging.

Do not:

• expose keys in frontend bundles;
• paste keys into tickets or chat tools;
• commit keys to Git;
• log Authorization headers;
• put secrets in URLs;
• reuse production keys in local experiments.

Troubleshooting

The page says missing

No usable workspace API key exists. Create a key, store it server-side, then retry.

Requests fail after rotation

Check that the new key is stored in production, all services were redeployed, workers were restarted and the old key is not still deployed somewhere.

Last used is empty

A key can be active but unused. Send a test Gateway or direct ingest request, then refresh the page.

I cannot rotate the key

Your role is read-only for this operation. Ask an owner or admin.

Related pages

• Authentication
• Gateway
• Direct ingest
• Metadata
• Tracing
• Idempotency