Developer Docs•stable•Updated 2026-07-06

Ingestion Keys

Understand ingestion credentials and when to use workspace API keys for direct usage ingestion.

Ingestion keys identify systems that send usage data to Kadryn.

In the current developer model, direct ingest requests should use a server-side Kadryn API key unless your workspace exposes a dedicated ingestion key workflow.

Use this page to understand the credential model and avoid mixing ingestion credentials with provider secrets.

What ingestion credentials are for

Ingestion credentials are used by trusted server-side systems that report AI usage events to Kadryn.

Typical senders include:

  • backend services;
  • batch workers;
  • ETL jobs;
  • provider usage importers;
  • external proxy pipelines;
  • scheduled backfills.

API keys and ingestion keys

CredentialUse it for
Kadryn API keyGeneral workspace authentication for direct ingest and developer APIs.
Ingestion keyA restricted credential for ingest-only pipelines, when enabled by your workspace.
Provider keyUpstream AI provider access, not direct ingest authentication.

If dedicated ingestion keys are not enabled in your workspace, use a Kadryn API key for direct ingest.

Recommended setup

  1. Create or rotate a Kadryn API key.
  2. Store it in the server-side environment of your ingestion worker.
  3. Add idempotency keys to each retryable event or batch.
  4. Send metadata for project, feature and environment.
  5. Verify events in Logs & Traces.
  6. Monitor rejected or invalid ingestion attempts in Diagnostics.

Example environment

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

Example direct ingest request

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

Rotation guidance

Rotate ingestion credentials when:

  • the key may have leaked;
  • the worker moved to a new environment;
  • a deployment system changed;
  • a vendor or contractor no longer needs access.

After rotation, check:

  • all workers have the new key;
  • old workers are stopped;
  • retry queues do not keep old credentials;
  • Logs & Traces show new activity;
  • invalid ingestion attempts stop.

Troubleshooting

Ingestion requests are rejected

Check authentication, payload shape, idempotency and required metadata.

Duplicate events appear

Use stable idempotency keys. Do not generate a new key for every retry of the same logical event.

Events are accepted but not useful

Improve metadata. At minimum, send project, feature and environment.

Related pages