OAuth-API

OAuth 2.0-Token-Endpunkt (RFC 6749 §3.2) für Agent-JWTs. grant_type refresh_token rotiert eine undurchsichtige Aktualisierungsanmeldeinformation (RFC 9700): Jede Verwendung liefert ein neues Paar; eine request_id (16 bis 200 Zeichen) bewirkt, dass ein exakter Wiederholungsversuch dieselbe Antwort zurückgibt, solange seine Anmeldeinformation und Gewährung aktiv sind und der Nachfolger noch aktuell ist, ohne eine Frist für Wiederholungen.

Jede andere Wiederverwendung eines ersetzten Refresh-Tokens widerruft die gesamte Familie (invalid_grant). Eine entfernte ausgewählte Mitgliedschaft oder ein Projekt gibt invalid_scope mit error_description beginnend mit "project_selection_inactive:" zurück; die Refresh-Berechtigung wird nicht verbraucht.

Entdecken Sie aktive Mitgliedschaften mit GET /api/projects, schneiden Sie sie mit der zuvor genehmigten Auswahl, und versuchen Sie es erneut mit projects= und einer neuen request_id. Beenden Sie niemals die Aktualisierungsfamilie für diesen Auswahlfehler.

Die angeforderte Bereichseinschränkung gilt unabhängig für jedes Projekt und die Identitätsbehörde; ein expliziter Bereich ohne Identität schließt die Identitätsbehörde aus. grant_type urn:ietf:params:oauth:grant-type:token-exchange (RFC 8693) mit subject_token_type urn:screenrig:token-type:identity-credential oder urn:screenrig:token-type:project-token antwortet mit unsupported_token_type: Alte Berechtigungsnachweise sind außer Dienst gestellt, und die Installation meldet sich erneut mit screenrig login an. resource (RFC 8707) ist https://api.<domain>/api oder fehlt; Projekte wählen bis zu 64 zugestimmte Projekt-IDs aus.

Auslassung wählt alle nur, wenn die Menge passt; sonst muss der Client eine Teilmenge wählen. project_id wählt eine während der Kompatibilitätsfreigabe. Ein Grant einer verbundenen App hat die einzelne Ressource https://api.<domain>/mcp, die ein Refresh weglassen kann.

Clients sind öffentlich (nur client_id) oder eine verbundene App, deren Metadaten private_key_jwt mit client_assertion_type urn:ietf:params:oauth:client-assertion-type:jwt-bearer und einem client_assertion (iss und sub sind client_id, aud der Aussteller oder dieser Endpunkt als ein String, exp innerhalb von 5 Minuten nach iat, ein jti einmalig verwendet, kid benennt einen seiner Schlüssel; EdDSA, ES256 oder RS256) authentifiziert. grant_type authorization_code löst den Code einer verbundenen App innerhalb von 60 Sekunden mit der exakten redirect_uri und dem PKCE code_verifier ein; resource muss fehlen oder die autorisierte sein; eine zweite Einlösung widerruft das durch den Code erstellte Grant. grant_type client_credentials ist ein Service-Client: er authentifiziert sich mit einer Client Assertion (einem seiner registrierten Schlüssel) oder seinem Geheimnis per HTTP Basic (client_secret_basic; ein Geheimnis im Body wird abgelehnt) und erhält ein 15-minütiges Service-Token für sein Projekt, Audience api oder (resource https://api.<domain>/mcp) mcp, Scope innerhalb seiner Fähigkeiten und Zugriffsebene, und kein Refresh-Token; 600 pro Client pro Stunde.

Fehler sind RFC 6749 JSON {error, error_description} mit Cache-Control no-store; während der Server sie nicht ausgibt, antwortet er mit temporarily_unavailable (503).

Ratenbegrenzungen antworten mit 429 rate_limited und Retry-After: 1200 Anfragen pro Client-Adresse pro Stunde an diesem und dem Widerruf-Endpunkt, 60 Aktualisierungen pro Berechtigung pro Stunde, 30 Austausche pro Legacy-Berechtigung pro Stunde. grant_type urn:ietf:params:oauth:grant-type:device_code (RFC 8628 §3.4) fragt eine Geräteanmeldung ab: authorization_pending bis eine Person sie genehmigt, slow_down bei zu frühem Abfragen (Intervall wächst dann um 5 Sekunden), access_denied bei Ablehnung, expired_token nach 10 Minuten, dann die Token-Antwort.

Eine neue Installation erhält ein Token-Paar; ein mit dem Zugriffstoken einer bestehenden Installation gestartetes Anmelden fügt das genehmigte Projekt diesem Grant hinzu und erhält nur ein Zugriffstoken, ohne das Refresh-Token zu rotieren. Das erneute Abfragen desselben device_code gibt dieselbe Antwort zurück, bis der Grant zuerst rotiert oder 10 Minuten vergehen, dann invalid_grant.

Nur POST, formkodiert, keine Abfragezeichenfolge.

RFC 8628 §3.1 Geräteautorisierung für `screenrig login`. scope ist access:manage (Standard), access:propose oder access:read; project_id schlägt das Projekt vor, das die Person genehmigt; name, agent_type, platform und version beschreiben die Installation und werden dem Genehmiger wie vom Gerät gemeldet angezeigt; install_source (optional) gibt an, woher sie installiert wurde, und wird am Agenten gespeichert, den die Genehmigung erstellt.

Ohne Autorisierung startet es eine neue Installation. Mit Authorization: Bearer und einem Agenten-Zugriffstoken mit Identitätsscope wird angefragt, ein Projekt zu dieser Installationserlaubnis hinzuzufügen oder ein Nur-Lesen-Projekt auf Verwalten zu erhöhen.

Die Person gibt user_code bei verification_uri ein (oder folgt verification_uri_complete) und genehmigt ihn im Dashboard; das Gerät fragt den Token-Endpunkt mit dem device_code alle Intervall-Sekunden ab.

Ratenbegrenzungen antworten mit 429 rate_limited und Retry-After: 10 pro Client-Adresse pro Stunde und 600 pro Stunde flächenweit, hinter den Endpunkten mit 1200 pro Adresse pro Stunde. Fehler sind RFC 6749 JSON mit Cache-Control no-store; solange der Server nicht ausgibt, antwortet er mit temporarily_unavailable (503). Nur POST, formularcodiert, keine Abfragezeichenfolge.

OAuth 2.0-Autorisierungsendpunkt für verbundene Apps (MCP-Clients). client_id ist eine Client-ID-Metadaten-Dokument-URL (https, Port 443, ohne Weiterleitungen abgerufen, maximal 64 KiB und 5 Sekunden, nur öffentliche Adressen) oder eine registrierte Client-ID.

Die Anfrage wird in dieser Reihenfolge geprüft: der Client, die exakte redirect_uri (eine http-Loopback-Weiterleitung an 127.0.0.1, [::1] oder localhost passt auf jedem Port), response_type code, code_challenge mit code_challenge_method S256, resource (https://api.<domain>/mcp, eine andere MCP-Ressource, deren Metadaten für geschützte Ressourcen diesen Server nennen, oder fehlend), dann scope (access:read, der Standard, access:propose, access:manage und Fähigkeitsnamen).

Ein unbekannter Client oder redirect_uri antwortet mit einer HTML-Fehlerseite und leitet niemals weiter; ein späterer Fehler leitet zur redirect_uri mit error, error_description, state und iss (RFC 9207) weiter.

Erfolg antwortet mit 303 zur Dashboard-Zustimmungsseite, wo eine Person das Projekt, die Zugriffsstufe (standardmäßig Nur Lesen, Vorschlagen oder Verwalten) und die Fähigkeiten wählt; Genehmigung leitet mit Code, Status und iss weiter. 30 Anfragen pro Client-Adresse pro Minute.

RFC 7009 Widerruf. Ein undurchsichtiges Aktualisierungstoken (oder ein JWT aus einer früheren Version), oder ein Agentenzugriffs-JWT, das dem Client ausgestellt wurde, widerruft seine Berechtigung; die Zugriffstoken der Berechtigung werden innerhalb von Sekunden abgelehnt. Ein unbekanntes, abgelaufenes oder fremdes Token antwortet ebenfalls mit 200. Nur POST, formularcodiert.

RFC 8414 Metadaten des Autorisierungsservers für den Agenten-Autorisierungsserver.

RFC 9728 Metadaten geschützter Ressourcen für /mcp, benannt durch resource_metadata jeder /mcp 401.

RFC 9728 Metadaten geschützter Ressourcen für /api.

Eine ausstehende Autorisierung einer verbundenen App für die Zustimmungsseite: der Name und die Domain des Clients, wie sie seine Metadaten angeben (kein Logo wird je abgerufen), ob es ein registrierter Client ist, der Redirect-Host sowie der angefragte Zugriffslevel und die Fähigkeiten. Unbekannte, abgelaufene oder abgeschlossene Autorisierungen sind not_found.

Genehmigt eine verbundene App für eines der Projekte der Person nach einem frischen Nachweis (Art oauth_authorization_approval, Betreff die Autorisierungs-ID): erstellt die Agentenidentität der App (Agententyp mcp_client, die verantwortliche Person), deren Mitgliedschaft und deren Berechtigung mit dem gewählten Zugriff (lesen oder verwalten; ausgelassen behält das angeforderte Level, standardmäßig lesen) und Fähigkeiten (eine Teilmenge der angeforderten) und antwortet mit redirect_uri, die code, state und iss enthält, zu der die Seite navigiert.

Der Code ist 60 Sekunden gültig. Ein auf Bildschirme beschränktes Mitglied verbindet keine Agenten, stellt keine Zugangsdaten aus und verwaltet nicht die Personen des Projekts: outside_screen_scope (den Projektinhaber fragen).

Lehnt eine verbundene App nach frischem Nachweis ab (kind oauth_authorization_denial) und antwortet mit der redirect_uri, die error=access_denied, state und iss trägt und zu der die Seite navigiert. Ein auf Bildschirme beschränktes Mitglied verbindet keine Agenten, stellt keine Zugangsdaten aus und verwaltet nicht die Personen des Projekts: outside_screen_scope (den Projektinhaber fragen).