Developer Docs•stable•Updated 2026-07-06

Authentication

Authenticate server-side systems to Kadryn with workspace API keys and safe authorization headers.

Kadryn developer APIs use server-side credentials.

Most developer requests authenticate with a Kadryn API key in the Authorization header.

Authorization: Bearer $KADRYN_API_KEY

Authentication model

Kadryn separates two credential types.

Credential	Purpose
Kadryn API key	Authenticates your backend, workers or platform service to Kadryn.
Provider key	Lets Kadryn call an upstream AI provider when Gateway routes traffic.

Never confuse them.

A Kadryn API key is sent by your service to Kadryn.

A provider key is stored in Kadryn and used only when Kadryn needs to call a provider route.

Required header

Send this header on developer API requests:

-H "Authorization: Bearer $KADRYN_API_KEY"

For JSON requests, also send:

-H "Content-Type: application/json"

Base URLs

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

Use KADRYN_API_BASE_URL for platform APIs such as direct ingest.

Use KADRYN_GATEWAY_BASE_URL for provider-compatible runtime requests.

Server-side only

Store Kadryn API keys only in trusted server-side environments.

Good places:

server environment variables;
a secret manager;
backend worker configuration;
CI/CD secret storage;
Kubernetes secrets managed by a secure operator.

Unsafe places:

frontend bundles;
browser local storage;
mobile app bundles;
public repositories;
query strings;
screenshots;
support tickets;
logs.

Example: Gateway authentication

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-Environment: prod" \
  -d '{
    "model": "gpt-4.1-mini",
    "messages": [
      {
        "role": "user",
        "content": "Hello from Kadryn"
      }
    ]
  }'

Example: Direct ingest authentication

curl "$KADRYN_API_BASE_URL/usage/events" \
  -H "Authorization: Bearer $KADRYN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: usage-event-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",
    "environment": "prod"
  }'

Permission errors

Authentication answers:

Who is calling Kadryn?

Authorization answers:

Is this caller allowed to do this?

If a request is authenticated but not authorized, check:

workspace membership;
API key status;
plan entitlements;
feature access;
provider route readiness;
policy mode;
billing state.

Troubleshooting

Invalid API key

Check that:

the key is copied exactly;
it is a Kadryn API key, not a provider key;
it belongs to the target workspace;
your backend was redeployed after secret changes;
the Authorization header starts with Bearer.

Missing authorization header

Send:

Authorization: Bearer $KADRYN_API_KEY

Do not send the key in the body or query string.

Works locally but not in production

Check:

production environment variables;
CI/CD secret injection;
container restart behavior;
workers that cache env variables;
staging keys accidentally used in production.