Gateway

Kadryn Gateway permet à votre application d’envoyer des requêtes provider IA via Kadryn au lieu d’appeler directement le provider.

Utilisez-le lorsque vous avez besoin de visibilité runtime, attribution des coûts, policy checks, caps budgétaires, routage provider, traçabilité et debug production pour le trafic IA.

Gateway est le chemin inline.

Si vous voulez seulement envoyer de l’usage historique ou capturé en externe dans Kadryn, utilisez Ingestion directe à la place.

Ce que vous allez faire

Dans ce guide, vous allez:

1. comprendre quand utiliser Gateway;
2. créer ou sélectionner une clé API Kadryn;
3. vérifier la readiness de la route provider;
4. envoyer une requête de test via Gateway;
5. attacher projet, feature, environnement et tracing métadonnées;
6. vérifier la requête dans Logs & Traces;
7. gérer fréquent erreurs et retries.

Quand utiliser Gateway

Utilisez Gateway lorsque Kadryn doit évaluer la requête avant ou pendant exécution provider.

Gateway est le bon chemin pour :

• logging centralisé des requêtes;
• suivi des coûts et tokens;
• projet, feature et environnement attribution;
• caps budgétaires et application des policies;
• checks de readiness des routes provider;
• fallback et routage visibilité;
• debug runtime dans Logs & Traces;
• production verification avec trace IDs et request group IDs.

Quand ne pas utiliser Gateway

N’utilisez pas Gateway lorsque vous avez seulement besoin d’importer de l’usage offline.

Utilisez l’ingestion directe lorsque :

• le trafic est déjà passé par un autre proxy;
• vous ne pouvez pas encore placer Kadryn inline;
• vous avez seulement besoin de visibilité des coûts après l’exécution;
• une source externe émet déjà des événements d’usage normalisés;
• vous faites un backfill d’usage historique.

Gateway donne un contrôle runtime. L’ingestion directe donne de l’observabilité sans proxyfier le trafic.

Flux de requête

1. Votre application envoie la requête IA à Kadryn Gateway.
2. Kadryn authentifie la requête avec votre clé API Kadryn.
3. Kadryn attache le contexte workspace depuis les headers et les métadonnées de clé API.
4. Kadryn évalue la configuration de routage, policy et guardrail.
5. Kadryn transmet la requête à la route provider sélectionnée.
6. Kadryn enregistre requête, tokens, coût, statut, latence et métadonnées de trace.
7. Votre application reçoit la réponse compatible provider.
8. Vous inspectez l’événement dans Logs & Traces.

Gateway est le point d’entrée runtime. Guardrails définit les policies. Costs analyse la dépense. Logs & Traces explique les requêtes individuelles.

URL de base

https://gateway.kadryn.com/v1

Pour les chat completions compatibles OpenAI :

POST https://gateway.kadryn.com/v1/chat/completions

Prérequis

Avant d’envoyer du trafic Gateway :

• créez une clé API Kadryn;
• configurez au moins une clé provider;
• vérifiez que la route provider est prête;
• identifier le projet et environnement;
• décidez quelles métadonnées vos policies exigent;
• décidez comment votre service gère retries et idempotence.

Requête quickstart

export KADRYN_API_KEY="kadryn_live_..."

curl https://gateway.kadryn.com/v1/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"
      }
    ]
  }'

Requête production

curl https://gateway.kadryn.com/v1/chat/completions \
  -H "Authorization: Bearer $KADRYN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Kadryn-Project: billing-api" \
  -H "X-Kadryn-Feature: invoice-assistant" \
  -H "X-Kadryn-Environment: prod" \
  -H "X-Kadryn-Request-Group-Id: invoice-run-2026-07-06-001" \
  -H "Idempotency-Key: invoice-run-2026-07-06-001:step-01" \
  -H "traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01" \
  -d '{
    "model": "gpt-4.1-mini",
    "messages": [
      {
        "role": "system",
        "content": "You are a support assistant for billing questions."
      },
      {
        "role": "user",
        "content": "Summarize the latest invoice status for this customer."
      }
    ],
    "temperature": 0.2
  }'

Headers requis

Les policies peuvent exiger des métadonnées techniquement optionnelles.

Headers recommandés

Readiness Gateway

La readiness Gateway peut apparaître ainsi :

Readiness des routes provider

Vérifiez dans Logs & Traces

Après avoir envoyé une requête, ouvrez :

Developers → Logs & Traces

Recherchez par :

• trace ID;
• request group ID;
• projet;
• feature;
• environnement;
• provider;
• model;
• statut;
• fallback usage;
• synthetic trafic.

Gestion des échecs

Règles de retry

Pour les échecs retryables :

1. conservez le même Idempotency-Key;
2. conservez le même X-Kadryn-Request-Group-Id;
3. préservez ou reliez le même contexte de trace;
4. utilisez un backoff exponentiel;
5. arrêtez après un nombre borné de tentatives.

Notes de sécurité

Do:

• gardez les credentials Gateway côté serveur;
• utilisez des clés séparées par environnement quand c’est possible;
• faites tourner les clés régulièrement;
• préserver trace IDs;
• masquez les payloads sensibles lorsque nécessaire.

Do not:

• exposer les clés API Kadryn dans le navigateur;
• log Authorization headers;
• placer des secrets dans les URLs;
• envoyer des clés API provider dans les métadonnées.

Checklist de production

• La clé API Kadryn existe.
• La clé provider existe.
• La route provider est prête.
• la clé API est uniquement côté serveur.
• La métadonnée project est envoyée.
• La métadonnée feature est envoyée.
• La métadonnée environment est envoyée.
• Les requêtes retryables utilisent des idempotency keys.
• Le tracing est propagé.
• Logs & Traces affiche le trafic de test.
• Les blocages policy sont compris.

Pages liées

• Clés API
• Provider clés
• Logs & Traces
• Gateway vs ingestion directe
• Erreurs Gateway