← Entwickler-Anleitungen

Wählen Sie Ihren Auth-Modus

Zwei Wege, das SDK zu authentifizieren — ein Entscheidungsbaum, ob Sie einen statischen API-Schlüssel oder ein nutzerbezogenes Session-JWT benötigen.

Das SDK unterstützt zwei Auth-Modi. Den richtigen zu wählen hängt davon ab, wo der Code, der das SDK aufruft, tatsächlich läuft — nicht davon, was bequemer ist.

Der Entscheidungsbaum

Läuft dieser Code auf Ihrem Server (Node.js-Backend, Cron-Job, interner Dienst)? → Der API-Schlüssel-Modus ist verfügbar. Übergeben Sie Ihren Schlüssel als apiKey. Erstellen Sie einen Self-Service auf der Detailseite Ihrer Anwendung in der Console (Regenerate API Key) — siehe Holen Sie sich Ihren API-Schlüssel — oder verwenden Sie unten den Session-JWT-Modus, wenn Sie lieber keinen statischen Schlüssel verwalten möchten.

const ai = new Quravin({
  endpoint: process.env.QURAVIN_URL,
  apiKey:   process.env.QURAVIN_KEY,   // aus Ihrem Secrets-Speicher — niemals committen
});

Läuft dieser Code im Browser eines Nutzers? → Verwenden Sie den Session-JWT-Modus. Ihr Server erstellt ein kurzlebiges, nutzerbezogenes Token und übergibt es der Seite — der Browser sieht niemals client_secret oder einen statischen API-Schlüssel.

const ai = new Quravin.Quravin({
  endpoint: "https://api.quravin.com",
  sessionToken: await fetchToken(),   // von Ihrem eigenen Backend-Endpunkt
  onTokenExpired: fetchToken,          // automatische Erneuerung bei 401
});

x-api-key vs. Session-JWT — sie sind nicht austauschbar

apiKey oben sendet die Anfrage als x-api-key: <key>. Dies ist ein veraltetes, anwendungsbezogenes, nicht org-gebundenes Credential, das die Plattform zugunsten nutzerbezogener JWTs ausläuft. Zwei Dinge sollten Sie wissen, bevor Sie darauf zurückgreifen:

• Kein Org-Wallet. Wenn Ihr Konto auf Wallet-Abrechnung läuft, gibt ein abrechenbarer POST /tickets-Aufruf mit einem reinen x-api-key 402 insufficient_credits zurück, selbst wenn das Wallet Ihrer Organisation Guthaben hat — der Schlüssel ist keiner Organisation zugeordnet und kann daher nicht aus einem Wallet ausgeben. Das ist so beabsichtigt, kein Bug.
• Keine nutzerbezogene Identität. Jeder Aufruf sieht so aus, als käme er von „der Anwendung”, nicht von einem bestimmten Nutzer — in Ordnung für einen Cron-Job, aber nicht, wenn Sie nutzerbezogene Audit-/Zuordnungsdaten oder eine pipelines[]-ACL benötigen, die enger gefasst ist als die gesamte Anwendung.

Wenn Abrechnung oder nutzerbezogene Zuordnung überhaupt eine Rolle spielt, verwenden Sie den Session-JWT-Modus — erstellen Sie das Token über POST /auth/token, nicht über x-api-key.

Ein Session-JWT erstellen: POST /auth/token

Ihr backend erstellt pro Nutzer ein kurzlebiges JWT, indem es den POST /auth/token-Endpunkt der Plattform aufruft, authentifiziert mit dem client_id/client_secret-Paar aus Holen Sie sich Ihren API-Schlüssel als HTTP-Basic-Auth:

curl -X POST "https://api.quravin.com/auth/token" \
  -H "Authorization: Basic $(echo -n 'client_id:client_secret' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "user-12345",
    "pipelines": ["translate-string"],
    "ttl_seconds": 900
  }'

Antwort:

{ "token": "eyJhbGciOi...", "token_type": "Bearer", "expires_in": 900 }

• subject (erforderlich) — die ID Ihrer Anwendung für diesen Nutzer; wird zum JWT-sub.
• pipelines (optional) — die ACL, die Sie für dieses Token möchten. Ein Nutzer kann nur Pipelines aufrufen, die in allowed_pipelines Ihrer Anwendung gelistet sind (in der Console festgelegt, siehe Holen Sie sich Ihren API-Schlüssel) — was Sie hier anfordern, wird serverseitig mit dieser Erlaubnisliste geschnitten, sodass Sie einem Nutzer nie mehr gewähren können, als Ihre Anwendung selbst darf. Lassen Sie dieses Feld weg, um ein Token zu erhalten, das auf die vollständige Erlaubnisliste Ihrer Anwendung beschränkt ist.
• ttl_seconds (optional) — Token-Lebensdauer, begrenzt auf 60–3600 Sekunden, Standard 900 (15 Min).

Übergeben Sie das zurückgegebene token dem Browser als sessionToken. Siehe Integrieren Sie es in Ihren eigenen Server für die vollständige Endpunkt- und Browser-Verdrahtung sowie für die veraltete Self-Signing-Alternative, die statt client_id/client_secret ein separat bereitgestelltes Signing-Secret verwendet.

Warum das wichtig ist

Ein statischer API-Schlüssel ist ein Bearer-Credential — wer ihn aus Ihrem Seitenquelltext liest, hat vollen Zugriff auf alles, was Ihre Anwendung kann. Ein Session-JWT ist auf einen einzelnen Nutzer beschränkt, läuft in Minuten ab, trägt eine pipelines[]-ACL und wird bei jedem Seitenaufruf frisch von Ihrem eigenen Server erstellt.

Faustregel: Wenn der Code in einen Browser ausgeliefert wird, oder wenn Abrechnung/nutzerbezogene Zuordnung eine Rolle spielt, braucht er ein Session-JWT, keinen statischen API-Schlüssel.

Weiter geht’s: Integrieren Sie es in Ihren eigenen Server zeigt den Token-Erstellungs-Endpunkt, der Session-JWTs ausstellt.