API OAuth

Point de terminaison de jeton OAuth 2.0 (RFC 6749 §3.2) pour les JWT d’agent. grant_type refresh_token fait tourner un justificatif opaque de rafraîchissement (RFC 9700) : chaque utilisation retourne une nouvelle paire ; un request_id (16 à 200 caractères) fait qu’une nouvelle tentative exacte retourne la même réponse tant que son justificatif et sa subvention sont actifs et que le successeur est encore courant, sans délai d’expiration de tentative écoulé.

Toute autre réutilisation d’un jeton de rafraîchissement remplacé révoque toute la famille (invalid_grant). Une adhésion ou un projet sélectionné supprimé renvoie invalid_scope avec error_description commençant par "project_selection_inactive:" ; le justificatif de rafraîchissement n’est pas consommé.

Découvrez les adhésions actives avec GET /api/projects, croisez-les avec la sélection consentie précédemment, et réessayez avec projects= et un nouveau request_id. Ne jamais terminer la famille d’actualisation pour cette erreur de sélection.

Le resserrement de la portée demandée s’applique indépendamment à chaque projet et à l’autorité d’identité ; une portée explicite sans identité exclut l’autorité d’identité. grant_type urn:ietf:params:oauth:grant-type:token-exchange (RFC 8693) avec subject_token_type urn:screenrig:token-type:identity-credential ou urn:screenrig:token-type:project-token répond unsupported_token_type : les identifiants hérités sont retirés, et l’installation se reconnecte avec screenrig login. resource (RFC 8707) est https://api.<domain>/api ou absent ; projects sélectionne jusqu’à 64 ID de projets consentis.

L’omission sélectionne tout seulement si l’ensemble convient ; sinon le client doit choisir un sous-ensemble. project_id en sélectionne un lors de la version de compatibilité. La subvention d’une app connectée a la ressource unique https://api.<domain>/mcp, qu’un rafraîchissement peut omettre.

Les clients sont publics (client_id seulement), ou une app connectée dont les métadonnées déclarent que private_key_jwt s’authentifie avec client_assertion_type urn:ietf:params:oauth:client-assertion-type:jwt-bearer et un client_assertion (iss et sub son client_id, aud l’émetteur ou ce point de terminaison comme une chaîne, exp dans les 5 minutes de iat, un jti utilisé une fois, kid nommant une de ses clés ; EdDSA, ES256 ou RS256). grant_type authorization_code échange un code d’app connectée dans les 60 secondes avec le redirect_uri exact et le code_verifier PKCE ; resource doit être absente ou celle autorisée ; un second échange révoque la subvention créée par le code. grant_type client_credentials est celui d’un client service : il s’authentifie avec une assertion client (une de ses clés enregistrées) ou son secret par HTTP Basic (client_secret_basic ; un secret dans le corps est refusé) et reçoit un jeton service de 15 minutes pour son projet, audience api ou (resource https://api.<domain>/mcp) mcp, scope dans ses capacités et niveau d’accès, et pas de jeton de rafraîchissement ; 600 par client par heure.

Les erreurs sont des JSON RFC 6749 {error, error_description} avec Cache-Control no-store ; tant que le serveur ne les émet pas, il répond temporarily_unavailable (503).

Les limites de débit répondent 429 rate_limited avec Retry-After : 1200 requêtes par adresse client par heure sur ce point de terminaison et celui de révocation, 60 rafraîchissements par concession par heure, 30 échanges par clé héritée par heure. grant_type urn:ietf:params:oauth:grant-type:device_code (RFC 8628 §3.4) interroge une connexion d’appareil : authorization_pending jusqu’à approbation par une personne, slow_down si interrogé avant l’intervalle (qui augmente alors de 5 secondes), access_denied en cas de refus, expired_token après 10 minutes, puis la réponse du jeton.

Une nouvelle installation reçoit une paire de jetons ; une connexion commencée avec le jeton d’accès d’une installation existante ajoute le projet approuvé à cette subvention et reçoit un jeton d’accès seulement, sans rotation du jeton de rafraîchissement. Interroger à nouveau le même device_code retourne la même réponse jusqu’à ce que la subvention tourne d’abord ou que 10 minutes passent, puis invalid_grant.

POST uniquement, encodé en formulaire, sans chaîne de requête.

RFC 8628 §3.1 autorisation d’appareil pour `screenrig login`. scope est access:manage (par défaut), access:propose ou access:read ; project_id suggère le projet que la personne approuve ; name, agent_type, platform et version décrivent l’installation et sont montrés à l’approbateur tels que rapportés par l’appareil ; install_source (facultatif) indique d’où elle a été installée et est conservé sur l’agent que l’approbation crée.

Sans Authorization, cela démarre une nouvelle installation. Avec Authorization: Bearer et un jeton d’accès agent portant le scope identity, il demande d’ajouter un projet à la subvention de cette installation, ou d’élever un projet Lecture seule à Gérer.

La personne saisit user_code à verification_uri (ou suit verification_uri_complete) et l’approuve dans le tableau de bord ; l’appareil interroge le point de jeton avec device_code à chaque intervalle de secondes.

Les limites de taux répondent 429 rate_limited avec Retry-After : 10 par adresse client par heure et 600 par heure pour toute la flotte, derrière les points de terminaison à 1200 par adresse par heure. Les erreurs sont JSON RFC 6749 avec Cache-Control no-store ; tant que le serveur ne l’émet pas, il répond temporarily_unavailable (503). POST uniquement, encodé en formulaire, sans chaîne de requête.

Point de terminaison d’autorisation OAuth 2.0 pour les apps connectées (clients MCP). client_id est une URL de document de métadonnées d’ID client (https, port 443, récupérée sans redirections, 64 KiB et 5 secondes au maximum, adresses publiques uniquement) ou un ID client enregistré.

La requête est validée dans cet ordre : le client, le redirect_uri exact (une redirection http de bouclage vers 127.0.0.1, [::1] ou localhost correspond sur n’importe quel port), response_type code, code_challenge avec code_challenge_method S256, resource (https://api.<domain>/mcp, une autre ressource MCP dont les métadonnées de ressource protégée nomment ce serveur, ou absente), puis scope (access:read, la valeur par défaut, access:propose, access:manage et les noms de capacités).

Un client inconnu ou redirect_uri répond par une page d’erreur HTML et ne redirige jamais ; toute erreur ultérieure redirige vers redirect_uri avec error, error_description, state et iss (RFC 9207).

Le succès répond par un 303 vers la page de consentement du tableau de bord, où une personne choisit le projet, le niveau d’accès (Lecture seule par défaut, Proposer ou Gérer) et les capacités ; l’approbation redirige avec code, état et iss. 30 requêtes par adresse client par minute.

Révocation RFC 7009. Un jeton opaque de rafraîchissement (ou un JWT de rafraîchissement d’une version précédente), ou un JWT d’accès agent, émis au client révoque sa concession ; les jetons d’accès de la concession sont refusés en quelques secondes. Un jeton inconnu, expiré ou étranger répond aussi 200. POST uniquement, encodé en formulaire.

Métadonnées du serveur d’autorisation RFC 8414 pour le serveur d’autorisation agent.

Métadonnées de ressource protégée RFC 9728 pour /mcp, nommées par resource_metadata de chaque /mcp 401.

Métadonnées de ressource protégée RFC 9728 pour /api.

Une autorisation d’application connectée en attente pour la page de consentement : le nom et le domaine du client tels que déclarés dans ses métadonnées (aucun logo n’est jamais récupéré), s’il est un client enregistré, l’hôte de redirection, ainsi que le niveau d’accès et les capacités demandés. Les autorisations inconnues, expirées ou réglées sont not_found.

Approuve une application connectée pour un des projets de la personne après une preuve fraîche (type oauth_authorization_approval, sujet l’identifiant d’autorisation) : elle crée l’identité d’agent de l’app (type agent mcp_client, la personne responsable), son adhésion et sa concession avec l’accès choisi (lecture ou gestion ; omis garde le niveau demandé, qui est lecture par défaut) et les capacités (un sous-ensemble de la demande), et répond avec redirect_uri, portant code, état et iss, vers laquelle la page navigue.

Le code est valide pendant 60 secondes. Un membre limité aux écrans ne connecte pas d’agents, n’émet pas d’identifiants et ne gère pas les personnes du projet : outside_screen_scope (demandez au propriétaire du projet).

Refuse une application connectée après une nouvelle preuve (kind oauth_authorization_denial) et répond avec le redirect_uri, portant error=access_denied, state et iss, vers lequel la page navigue. Un membre limité aux écrans ne connecte pas d’agents, n’émet pas d’identifiants et ne gère pas les personnes du projet : outside_screen_scope (demandez au propriétaire du projet).