BazaarLinkBazaarLink
Anmelden
DokumentationAPI-ReferenzSDK-ReferenzAgentic-NutzungKI-Skills
Inhalt

OAuth PKCE

OAuth PKCE

OAuth 2.0 PKCE (Proof Key for Code Exchange) ermöglicht öffentlichen Client-Apps (Browser-SPAs, mobile Apps) API-Aufrufe im Namen einzelner Benutzer ohne clientseitige Speicherung eines langlebigen Server-Secrets.

Wann OAuth PKCE verwenden

  • Browser-SPA oder mobile App mit benutzerbezogener Abrechnung
  • Multi-Tenant SaaS — jeder Endbenutzer zahlt für seine eigene API-Nutzung
  • Sie können kein Shared Secret clientseitig speichern (öffentlicher Client)
  • Sie benötigen pro Benutzer einen eigenen, widerrufbaren Schlüssel (er läuft nicht von selbst ab) statt eines einzelnen gemeinsamen API-Schlüssels

Was Ihre Benutzer sehen

Beschreiben Sie diese Schritte auf Ihrem eigenen Anmeldebildschirm:

  1. In Ihrer App wählen sie „Mit BazaarLink anmelden“ (oder wie auch immer Sie die Schaltfläche nennen).
  2. Ihr Browser öffnet die BazaarLink-Autorisierungsseite. Sind sie noch nicht angemeldet, melden sie sich zuerst an und kehren automatisch zu dieser Seite zurück.
  3. Die Seite zeigt die Adresse Ihrer App und was beim Erlauben passiert: Für die App wird ein neuer API-Schlüssel erstellt, die Nutzung wird ihrem BazaarLink-Guthaben belastet, und sie können den Schlüssel jederzeit widerrufen. Sie können den Schlüssel benennen und ein monatliches Ausgabenlimit festlegen (beides optional).
  4. Sie klicken auf „Erlauben“ und werden zu Ihrer App zurückgeleitet. Klicken sie auf „Ablehnen“, wird kein Schlüssel erstellt, Ihre App wird nicht benachrichtigt und sie sehen die Seite „Zugriff abgelehnt“.
  5. Um den Zugriff später zu widerrufen, öffnen sie die Seite „API-Schlüssel“ (https://bazaarlink.ai/keys) und deaktivieren oder löschen den nach Ihrer App benannten Schlüssel.

So funktioniert es

Schritt 1 — Authentifizierung initiieren — Generieren Sie einen zufälligen code_verifier (einen langen Zufallsstring) und dessen SHA-256-Hash als code_challenge, dann leiten Sie den Benutzer zur BazaarLink-Auth-Seite weiter.

https://bazaarlink.ai/auth?callback_url=https://yourapp.com/callback&code_challenge=CODE_CHALLENGE&code_challenge_method=S256

Parameter der Autorisierungs-URL

  • callback_url (erforderlich) — wohin der Benutzer nach dem Erlauben zurückkehrt. Regeln siehe unten.
  • code_challenge (erforderlich) — der base64url-kodierte SHA-256-Hash Ihres code_verifier (43 Zeichen, ohne Padding).
  • code_challenge_method (erforderlich) — muss S256 sein.
  • state (optional) — Ihr eigener undurchsichtiger CSRF-Wert, 1 bis 256 druckbare ASCII-Zeichen. BazaarLink gibt ihn unverändert als &state=… direkt nach dem code zurück. Ein fehlerhafter state lässt die Autorisierungsseite „Ungültige Autorisierungsanfrage“ anzeigen.
  • key_label (optional) — bis zu 100 Zeichen. Füllt den Schlüsselnamen auf der Einwilligungsseite vor (der Benutzer kann ihn weiterhin ändern). Zu lange oder leere Labels werden ignoriert.
  • Headless tools (CLI / desktop, no callback_url) — omit callback_url. After the user allows, the page shows a one-time code (valid 5 minutes, single use) for them to enter into your tool; exchange it exactly like a redirected code. The page cannot show which app is asking, so tell users to enter the code only in a tool they started themselves.

Nicht unterstützt

  • workspace_id und required_workspace_id — nicht unterstützt. Der Schlüssel gehört immer zum eigenen Konto des Benutzers.
  • code_challenge_method=plain — nicht unterstützt (nur S256).

Regeln für die callback_url

  • Sie muss mit https:// beginnen. http:// wird nur für localhost, 127.0.0.1 und [::1] (beliebiger Port) akzeptiert; die Einwilligungsseite zeigt dann einen Hinweis zur lokalen Entwicklung.
  • Kein Fragment (#), kein Benutzername oder Passwort in der URL, höchstens 2048 Zeichen.
  • Die Einwilligungsseite zeigt den Hostnamen Ihres Callbacks, damit der Benutzer sieht, welche App anfragt.
  • Nachdem der Benutzer erlaubt hat, wird der Browser mit angehängtem code=… zu Ihrer callback_url geleitet (und mit state=…, wenn Sie einen gesendet haben; ein vorhandener Query-String bleibt erhalten). Der code ist 10 Minuten gültig und nur einmal verwendbar.

Schritt 2 — Code gegen API-Schlüssel tauschen — Nachdem der Benutzer die Anfrage autorisiert hat, leitet BazaarLink mit einem einmaligen code zu Ihrer callback_url weiter. Der code ist 10 Minuten gültig und nur einmal verwendbar; ein falscher code_verifier macht ihn ungültig. Senden Sie code, code_verifier und code_challenge_method (alle drei erforderlich) per POST, um den API-Schlüssel des Benutzers zu erhalten.

curl https://bazaarlink.ai/api/v1/auth/keys \
-H "Content-Type: application/json" \
-d '{
  "code": "<CODE_FROM_CALLBACK_URL>",
  "code_verifier": "<CODE_VERIFIER>",
  "code_challenge_method": "S256"
}'

# Response
# { "key": "sk-bl-...", "user_id": "..." }

Schritt 3 — Benutzerbezogenen Schlüssel verwenden — Der zurückgegebene Schlüssel ist ein normaler BazaarLink-API-Schlüssel, der dem autorisierenden Benutzer gehört — die Nutzung wird dem Guthaben dieses Benutzers belastet, nicht Ihrem.

curl https://bazaarlink.ai/api/v1/chat/completions \
-H "Authorization: Bearer sk-bl-..." \
-H "Content-Type: application/json" \
-d '{"model": "google/gemini-3.5-flash", "messages": [{"role": "user", "content": "Hello"}]}'

JavaScript-Beispiel (Browser)

// 1) Create a verifier + S256 challenge, then send the user to BazaarLink
const b64url = (buf) => btoa(String.fromCharCode(...new Uint8Array(buf)))
.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
const verifier = b64url(crypto.getRandomValues(new Uint8Array(32)));
const challenge = b64url(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier)));
sessionStorage.setItem("bl_verifier", verifier);
// "state" is optional: BazaarLink hands it back unchanged next to the code.
const state = b64url(crypto.getRandomValues(new Uint8Array(16)));
sessionStorage.setItem("bl_state", state);
location.href =
"https://bazaarlink.ai/auth?callback_url=" + encodeURIComponent(location.origin + "/callback") +
"&code_challenge=" + challenge + "&code_challenge_method=S256&state=" + state;

// 2) On /callback: check your own state, then exchange the one-time code for a user key
const params = new URLSearchParams(location.search);
if (params.get("state") !== sessionStorage.getItem("bl_state")) throw new Error("state mismatch");
const res = await fetch("https://bazaarlink.ai/api/v1/auth/keys", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
  code: params.get("code"),
  code_verifier: sessionStorage.getItem("bl_verifier"),
  code_challenge_method: "S256",
}),
});
if (!res.ok) throw new Error((await res.json()).error?.message ?? "exchange failed"); // 403 invalid_code: ask the user to authorize again
const { key } = await res.json(); // use as: Authorization: Bearer <key>
Sicherheit: Nur S256
Setzen Sie code_challenge_method auf S256 (SHA-256-Hash). Nur S256 wird unterstützt: Anfragen mit plain oder ohne code_challenge_method werden mit HTTP 400 abgelehnt.
Hinweis
Lehnt der Nutzer ab, leitet BazaarLink nicht auf Ihre callback_url zurück und benachrichtigt Ihre App nicht. Es wird nur eine Seite „Zugriff abgelehnt“ angezeigt, sodass /auth nie als Open Redirect dienen kann. Behandeln Sie den Zustand „nicht autorisiert“ in Ihrer App (z. B. per Timeout oder Wiederholen-Schaltfläche).

Die Seite /auth und POST /api/v1/auth/keys werden von https://bazaarlink.ai ausgeliefert (nicht von api.bazaarlink.ai). Der erhaltene Schlüssel funktioniert mit beiden Basis-URLs: https://bazaarlink.ai/api/v1 und https://api.bazaarlink.ai/v1.

Legt der Nutzer bei der Autorisierung ein Ausgabenlimit fest, ist es ein Monatslimit und wird mit dem Monatszeitraum des Kontos zurückgesetzt.

Fehler

Fehler haben das OpenAI-Format {"error":{"message","type","code"}}. POST /api/v1/auth/keys kann zurückgeben:

  • 400 invalid_code_challenge_method — code_challenge_method fehlt, ist plain oder etwas anderes als S256.
  • 400 — der JSON-Body ist ungültig, oder code / code_verifier fehlt.
  • 403 invalid_code — der code ist unbekannt, abgelaufen oder bereits verwendet, der code_verifier ist falsch oder das Konto ist nicht mehr zugelassen. Alle diese Fälle liefern absichtlich dieselbe Meldung, damit ein Aufrufer sie nicht unterscheiden kann. Ein falscher code_verifier macht den code ebenfalls ungültig: Bitten Sie den Benutzer, erneut zu autorisieren.
  • 429 rate_limited — mehr als 30 Austauschversuche in 10 Minuten von einer IP (siehe Header Retry-After).
  • 429 key_total_cap — das Konto besitzt bereits die maximal zulässigen 200 API-Schlüssel.
  • 405 — nur POST wird akzeptiert.

Code von Ihrem Server aus erstellen (Management-Schlüssel)

Der Inhaber eines persönlichen Management-Schlüssels kann den Autorisierungscode direkt mit POST /api/v1/auth/keys/code erstellen, ohne den Nutzer über die Browserseite zu leiten (OpenRouter-kompatibel). Der Code ist an den Inhaber des Management-Schlüssels gebunden; der Schlüssel, den Sie dafür eintauschen, ist daher ein Standardschlüssel im Konto dieses Inhabers, mit dem hier gewählten Limit, Zeitraum, Ablaufdatum und Namen. Nutzen Sie das, wenn Ihr eigenes Tool bereits einen Management-Schlüssel besitzt und einer App einen begrenzten Schlüssel übergeben will. Der Austausch (POST /api/v1/auth/keys) ist derselbe wie oben.

  • callback_url (erforderlich) und code_challenge + code_challenge_method=S256 (erforderlich) — dieselben Regeln wie bei der Autorisierungs-URL.
  • key_label (optional) — bis zu 100 Zeichen; der Name des Schlüssels. Standard: "App: <Ihr Callback-Host>".
  • limit (optional) — Ausgabenlimit in USD, 0 oder mehr; 0 oder fehlend bedeutet kein Limit.
  • usage_limit_type (optional) — daily, weekly oder monthly: wie oft das Limit zurückgesetzt wird. Wird nur zusammen mit limit verwendet; Standard ist monthly.
  • expires_at (optional) — Ablaufzeitpunkt des Schlüssels: ISO-8601-UTC-Zeit mit Sekunden in der Zukunft, zum Beispiel 2026-12-31T23:59:59Z. Werte nur mit Minutengenauigkeit werden abgelehnt. Fehlt der Wert, bleibt der Schlüssel gültig, bis er widerrufen wird.
  • workspace_id — nicht unterstützt (400). spawn_agent und spawn_cloud werden akzeptiert und ignoriert.
curl https://bazaarlink.ai/api/v1/auth/keys/code \
-H "Authorization: Bearer sk-bl-YOUR_MGMT_KEY" \
-H "Content-Type: application/json" \
-d '{
  "callback_url": "https://yourapp.com/callback",
  "code_challenge": "<CODE_CHALLENGE>",
  "code_challenge_method": "S256",
  "key_label": "My app",
  "limit": 10,
  "usage_limit_type": "monthly",
  "expires_at": "2026-12-31T23:59:59Z"
}'

# Response
# { "data": { "id": "<ONE_TIME_CODE>", "app_id": 123456789, "created_at": "2026-10-22T12:00:00.000Z" } }
# Then POST { "code": "<ONE_TIME_CODE>", "code_verifier": "<CODE_VERIFIER>", "code_challenge_method": "S256" } to /api/v1/auth/keys

Antwort: { "data": { "id", "app_id", "created_at" } }. id ist der einmalige Code zum Eintauschen (10 Minuten gültig, nur einmal). BazaarLink hat kein App-Register, daher ist app_id eine stabile ganze Zahl, die aus Ihrer Callback-Adresse abgeleitet wird: dieselbe Adresse erhält immer dieselbe app_id.

  • 401 unauthorized — kein Bearer-Schlüssel oder der Schlüssel ist unbekannt.
  • 403 management_key_required — der Schlüssel ist kein persönlicher Management-Schlüssel (Standardschlüssel und Management-Schlüssel von Organisationen werden abgelehnt).
  • 403 account_not_allowed — der Inhaber des Schlüssels ist gesperrt oder gelöscht.
  • 400 — invalid_callback_url, invalid_code_challenge_method, invalid_code_challenge, invalid_expires_at, workspace_not_supported oder ein fehlerhafter Body.
  • 429 rate_limited — mehr als 30 Codes pro Stunde für einen Inhaber oder 120 pro Stunde von einer IP (siehe Retry-After).

Der Schlüssel, den Sie erhalten

  • Ein Standard-BazaarLink-API-Schlüssel (sk-bl-…), derselbe Typ wie ein auf der Seite „API-Schlüssel“ erstellter Schlüssel. Er läuft nicht von selbst ab.
  • Die Nutzung wird dem BazaarLink-Guthaben des Benutzers belastet. Legt der Benutzer auf der Einwilligungsseite ein Ausgabenlimit fest, ist es ein Monatslimit.
  • Er funktioniert mit beiden Basis-URLs: https://bazaarlink.ai/api/v1 und https://api.bazaarlink.ai/v1.
  • Er zählt zum Limit von 200 Schlüsseln pro Konto und erscheint in der Liste „API-Schlüssel“ des Benutzers, wo er ihn jederzeit deaktivieren oder löschen kann.
  • Gesperrte oder gelöschte Konten können keine Apps autorisieren, und ein vor einer Sperrung ausgestellter code wird beim Austausch abgelehnt (403 invalid_code).

Was Sie erhalten

  • Authorization Code + PKCE-Flow für öffentliche Client-Anwendungen
  • Abrechnung pro Benutzer: Jeder Benutzer bezahlt seine Nutzung von seinem eigenen Guthaben
  • Ein eigener Schlüssel pro Benutzer, aufgeführt auf der Seite „API-Schlüssel“ des Benutzers, wo er ihn widerrufen kann
Support
Hi! How can we help you?
Send a message and we'll get back to you soon.
OAuth PKCE | BazaarLink