Overview

Understand the API reference model.

Scope

This page describes shared behavior used by multiple Kadryn API endpoints.

Authentication

Use a Kadryn API key in the Authorization header.

Authorization: Bearer $KADRYN_API_KEY

Keep API keys server-side. Do not expose them in browsers, mobile apps, URLs or client logs.

Request design

• Use JSON request bodies.
• Send stable metadata for project, feature and environment.
• Use idempotency keys for retryable writes.
• Preserve traceparent or an equivalent trace context.
• Avoid sending secrets or provider credentials in metadata.

Response design

Kadryn responses should be treated as structured JSON. Store identifiers, request IDs and trace references when you need later debugging or support workflows.

Errors

Handle authentication, authorization, validation, policy, rate limit, provider and server errors separately. Do not retry non-retryable policy or validation errors without changing the input.

Production notes

• Bound retries with backoff.
• Keep payloads small and explicit.
• Use cursor pagination for large result sets.
• Record request IDs without logging secrets.
• Validate responses at your integration boundary.

Related pages

• /docs/api-reference
• /docs/developer-docs