Zum Hauptinhalt springen
Lass Personen sich mit Phaseo anmelden und in deiner App ihre eigenen Credits ausgeben: OAuth 2.1 mit PKCE gibt deinem Server ein Zugriffstoken, und ein serverseitiger Proxy hängt es an jeden Gateway-Aufruf an. Am Ende hast du eine lokale App mit Anmeldung, sitzungsgebundenen Tokens, die sich erneuern, Modellsuche, einem Chat-Ablauf über /responses und einem Tester für weitere Endpunkte. Das Beispiel ermittelt die OAuth-Endpunkte von Phaseo, prüft bei der Rückkehr state und iss, erneuert Tokens sicher und widerruft den Schlüssel, wenn sich die Person abmeldet. Damit ein Coding-Agent dieselbe App von Grund auf baut, füge diesen Prompt ein:

Baue eine angemeldete Next.js-Workbench mit OAuth und einem einheitlichen Phaseo-Proxy.

In Cursor öffnen

Wie das Beispiel aufgebaut ist

Das Beispiel liegt in examples/oauth-client-nextjs: Weil die Anmeldung von den Gateway-Aufrufen getrennt ist, sieht ein Anmeldeproblem nie wie ein Modellproblem aus, und alle Endpunkte teilen sich eine Stelle, die Tokens verwaltet.

Ausführen

Du brauchst Node.js, eine OAuth-App mit http://localhost:3000/auth/callback (oder deinem eigenen Callback) als Weiterleitungs-URI und ein langes zufälliges Sitzungsgeheimnis. Lege die OAuth-App unter Einstellungen → OAuth-Apps oder mit der OAuth-Clients-API an.
1

Installieren

2

.env.local anlegen

Trage die Werte ein:Das Beispiel liest alle Werte nur auf dem Server. Lege das Client-Secret oder das Session-Secret nie in eine NEXT_PUBLIC_-Variable.Das Beispiel ermittelt die Endpunkte für Autorisierung, Token, Widerruf und Userinfo über https://api.phaseo.app/.well-known/oauth-authorization-server und fordert openid email profile gateway:access an. Mit gateway:access kann das Token das Gateway aufrufen.
3

Den Entwicklungsserver starten

Öffne http://localhost:3000, melde dich an und öffne das Dashboard.

Prüfen, ob es funktioniert hat

  • Die Anmeldung kehrt zu deiner Callback-URL zurück und legt eine Sitzung an.
  • Das Dashboard listet Modelle über /api/gateway/models auf.
  • Eine Chatrunde über /api/gateway/responses erhält eine Antwort, und keine Browseranfrage enthält das Zugriffstoken.
  • Ein Pfad außerhalb der Proxy-Zulassungsliste wird abgelehnt.

Laufzeiten der Tokens

Der Token-Endpunkt gibt zwei Tokens zurück:
  • Bei jeder Erneuerung rotieren. Jede Erneuerung liefert ein neues Zugriffstoken und ein neues Refresh-Token. Speichere beide und verwirf die alten: Das alte Zugriffstoken funktioniert sofort nicht mehr, und das alte Refresh-Token lässt sich nicht erneut verwenden.
  • Nach Ablauf erneuern. Du kannst erneuern, nachdem das Zugriffstoken abgelaufen ist, solange das Refresh-Token noch gültig ist.
  • Ein Refresh-Token nie wiederverwenden. Eine zweite Verwendung beendet die Anmeldung. Phaseo behandelt es als geleaktes Token und widerruft das Zugriffstoken und alle Refresh-Tokens dieser Anmeldung, sodass sich die Person erneut anmelden muss.
  • Scopes werden nur kleiner. Eine Erneuerung fügt nie Scopes hinzu. Sie behält die Scopes, denen die Person zugestimmt hat, abzüglich derer, die sie inzwischen entfernt hat.
  • Wenn die Erneuerung fehlschlägt. Die Erneuerung schlägt fehl, sobald die Person deine App widerruft, ihren Schlüssel widerruft oder deaktiviert, einen Scope entfernt, den der Schlüssel braucht (zum Beispiel gateway:access), oder den Workspace verlässt. Das Entfernen von gateway:access widerruft außerdem den Schlüssel, sodass sein Zugriffstoken sofort nicht mehr funktioniert. Den Scope erneut zu erteilen, bringt das Refresh-Token nicht zurück. Schicke die Person erneut durch die Anmeldung.
  • Erneutes Anmelden erneuert den Schlüssel. Es erneuert denselben Schlüssel, statt einen neuen hinzuzufügen, unabhängig davon, ob du resource=https://api.phaseo.app/v1 sendest. Du erhältst ein neues Zugriffstoken und ein neues Refresh-Token, die bisherigen funktionieren nicht mehr, und der Schlüssel behält die Ausgaben dieses Monats. Sein monatliches Ausgabenlimit wird zu dem, dem die Person gerade zugestimmt hat. Das Refresh-Token einer früheren Anmeldung wird einfach abgelehnt, und es an den Token- oder Revoke-Endpunkt zu senden, beendet die neue Anmeldung nicht.
  • Ein pausierter Schlüssel blockiert die Anmeldung. Ist einer der Schlüssel deiner App für diese Person und diesen Workspace pausiert, unabhängig von seiner Ressource, gibt der Token-Endpunkt invalid_grant zurück, bis jemand den Schlüssel unter Einstellungen → API-Schlüssel wieder aktiviert. Die Erneuerung funktioniert nur, solange der Schlüssel nicht widerrufen ist: Nach einer Abmeldung oder einem anderen Widerruf stellt die Anmeldung einen neuen Schlüssel aus, dessen Limits und Ausgaben bei null beginnen.
  • Mit Revoke abmelden. Sende das Refresh-Token an https://api.phaseo.app/oauth/revoke. Das widerruft den Schlüssel und alle Refresh-Tokens der Anmeldung, auch eines, das eine Erneuerung kurz zuvor ausgestellt hat.

Ausgabenlimits

Auf dem Zustimmungsbildschirm legt die Person ein monatliches Ausgabenlimit für deine App fest: standardmäßig $20.00, einen anderen Betrag oder kein Limit. Sobald der Schlüssel diesen Betrag in einem Kalendermonat ausgegeben hat, geben Gateway-Anfragen 429 mit key_limit_exceeded zurück, bis der nächste Monat beginnt oder die Person das Limit unter Einstellungen → API-Schlüssel erhöht. Egal welche Scopes sie hat: Deine App kann dieses Limit über die API weder aufheben noch umgehen. Sie kann API-Schlüssel nur umbenennen oder löschen. Sie kann keine Schlüssel erstellen oder rotieren, weder Limits, Status noch Ablauf eines Schlüssels ändern, keine Verwaltungsschlüssel oder vertrauenswürdigen Workloads anlegen, keine Mitglieder hinzufügen, keine Budgets, Guardrails, Ratenlimits oder Ausgaberegeln ändern und weder die Preislimits des Workspace für das Routing noch seinen BYOK-Fallback auf Credits ändern.

Bevor du es auslieferst

  • Die Zulassungsliste kürzen. lib/gateway.ts erlaubt die Pfade, die die Workbench aufruft, sowie den Jobstatus unter videos/ und music/generate/. Behalte nur die Pfade, die dein Produkt aufruft.
  • Erneuerungen instanzübergreifend teilen. lib/oauth.ts teilt eine Erneuerung im Arbeitsspeicher zwischen parallelen Anfragen. Wenn du mehr als eine Serverinstanz betreibst, verlagere das in einen gemeinsamen Speicher, sonst können zwei Instanzen mit demselben Token erneuern und damit die Anmeldung beenden.
  • Die ganze Unterhaltung senden. Das Gateway speichert keine Antworten und lehnt previous_response_id ab, also sende frühere Runden erneut in input.
  • Den Tester ersetzen. Behalte die Workbench für die interne QA und baue zweckgebundene Abläufe für Endnutzer.
Für eine App mit API-Schlüssel ohne Anmeldung beginnst du mit der Next.js-Web-Chat-App.
Zuletzt geändert am 13. November 2026