API OAuth

Endpoint token OAuth 2.0 (RFC 6749 §3.2) per JWT agenti. grant_type refresh_token ruota una credenziale di refresh opaca (RFC 9700): ogni uso restituisce una nuova coppia; un request_id (16-200 caratteri) fa sì che un retry esatto restituisca la stessa risposta mentre la sua credenziale e concessione sono attive e il successore è ancora corrente, senza scadenza retry per tempo trascorso.

Qualsiasi altro riutilizzo di un refresh token superato revoca tutta la famiglia (invalid_grant). Un’appartenenza o progetto selezionato rimosso restituisce invalid_scope con error_description che inizia con "project_selection_inactive:"; la credenziale di refresh non viene consumata.

Scopri le membership attive con GET /api/projects, incrocia con la selezione precedentemente acconsentita e riprova con projects= e un nuovo request_id. Non terminare mai la famiglia di aggiornamenti per questo errore di selezione.

La restrizione dell’ambito richiesto si applica indipendentemente a ogni progetto e all’autorità d’identità; un ambito esplicito senza identità esclude l’autorità d’identità. grant_type urn:ietf:params:oauth:grant-type:token-exchange (RFC 8693) con subject_token_type urn:screenrig:token-type:identity-credential o urn:screenrig:token-type:project-token risponde unsupported_token_type: le credenziali legacy sono ritirate e l’installazione effettua nuovamente l’accesso con screenrig login. resource (RFC 8707) è https://api.<domain>/api o assente; projects seleziona fino a 64 ID progetto con consenso.

L’omissione seleziona tutto solo se il set ci sta; altrimenti il client deve scegliere un sottoinsieme. project_id seleziona uno durante il rilascio di compatibilità. Il grant di un’app connessa ha la singola risorsa https://api.<domain>/mcp, che un refresh può omettere.

I client sono pubblici (solo client_id), o un’app connessa il cui metadata dichiara private_key_jwt che si autentica con client_assertion_type urn:ietf:params:oauth:client-assertion-type:jwt-bearer e un client_assertion (iss e sub sono il suo client_id, aud l’emittente o questo endpoint come stringa unica, exp entro 5 minuti da iat, un jti usato una volta, kid che nomina una delle sue chiavi; EdDSA, ES256 o RS256). grant_type authorization_code riscatta il codice di un’app connessa entro 60 secondi con redirect_uri esatto e PKCE code_verifier; resource deve essere assente o autorizzata; un secondo riscatto revoca il grant creato dal codice. grant_type client_credentials è di un client di servizio: si autentica con un client assertion (una delle sue chiavi registrate) o il suo segreto via HTTP Basic (client_secret_basic; un segreto nel corpo è rifiutato) e riceve un token di servizio di 15 minuti per il suo progetto, audience api o (resource https://api.<domain>/mcp) mcp, scope entro capacità e livello di accesso, senza refresh token; 600 per client all’ora.

Gli errori sono JSON RFC 6749 {error, error_description} con Cache-Control no-store; mentre il server non li emette risponde temporarily_unavailable (503).

I limiti di frequenza rispondono 429 rate_limited con Retry-After: 1200 richieste per indirizzo client all’ora su questo e l’endpoint di revoca, 60 aggiornamenti per concessione all’ora, 30 scambi per credenziale legacy all’ora. grant_type urn:ietf:params:oauth:grant-type:device_code (RFC 8628 §3.4) interroga un accesso dispositivo: authorization_pending finché una persona non lo approva, slow_down se interrogato prima dell’intervallo (che poi cresce di 5 secondi), access_denied se negato, expired_token dopo 10 minuti, poi la risposta token.

Una nuova installazione riceve una coppia di token; un accesso iniziato con il token di accesso di un’installazione esistente aggiunge il progetto approvato a quella concessione e riceve solo un token di accesso, senza ruotare il token di aggiornamento. Il polling dello stesso device_code restituisce la stessa risposta finché la concessione non ruota per prima o passano 10 minuti, poi invalid_grant.

Solo POST, codificato form, senza stringa di query.

RFC 8628 §3.1 autorizzazione dispositivo per `screenrig login`. scope è access:manage (default), access:propose o access:read; project_id suggerisce il progetto approvato dalla persona; name, agent_type, platform e version descrivono l’installazione e sono mostrati all’approvatore come riportato dal dispositivo; install_source (opzionale) indica da dove è stata installata e viene conservato sull’agente creato dall’approvazione.

Senza Authorization avvia una nuova installazione. Con Authorization: Bearer e un token di accesso agente con ambito identity chiede di aggiungere un progetto alla concessione di quell’installazione, o di elevare un progetto Solo lettura a Gestisci.

La persona inserisce user_code su verification_uri (o segue verification_uri_complete) e lo approva nel dashboard; il dispositivo interroga l’endpoint token con device_code ogni intervallo di secondi.

I limiti di frequenza rispondono 429 rate_limited con Retry-After: 10 per indirizzo client all’ora e 600 all’ora per tutta la flotta, dietro i 1200 per indirizzo all’ora degli endpoint. Gli errori sono JSON RFC 6749 con Cache-Control no-store; mentre il server non li emette risponde temporarily_unavailable (503). Solo POST, codificato in form, senza query string.

Endpoint di autorizzazione OAuth 2.0 per app connesse (client MCP). client_id è un URL documento metadati client ID (https, porta 443, recuperato senza redirect, massimo 64 KiB e 5 secondi, solo indirizzi pubblici) o un client id registrato.

La richiesta viene convalidata in quest'ordine: il client, il redirect_uri esatto (un reindirizzamento http di loopback a 127.0.0.1, [::1] o localhost corrisponde su qualsiasi porta), response_type code, code_challenge con code_challenge_method S256, resource (https://api.<domain>/mcp, un'altra risorsa MCP i cui metadati di risorsa protetta nominano questo server, o assente), poi scope (access:read, il predefinito, access:propose, access:manage e i nomi delle capacità).

Un client sconosciuto o redirect_uri risponde con una pagina errore HTML e non reindirizza mai; ogni errore successivo reindirizza al redirect_uri con error, error_description, state e iss (RFC 9207).

Il successo risponde con 303 alla pagina di consenso del dashboard, dove una persona sceglie il progetto, il livello di accesso (Solo lettura di default, Proponi o Gestisci) e le capacità; l’approvazione reindirizza con codice, stato e iss. 30 richieste per indirizzo client al minuto.

Revoca RFC 7009. Una credenziale di aggiornamento opaca (o un JWT di aggiornamento di versione precedente), o un JWT di accesso agente, emesso al client revoca la sua concessione; i token di accesso della concessione sono rifiutati entro pochi secondi. Un token sconosciuto, scaduto o esterno risponde comunque 200. Solo POST, codificato in form.

Metadati server di autorizzazione RFC 8414 per il server di autorizzazione agente.

Metadati risorsa protetta RFC 9728 per /mcp, nominati da resource_metadata di ogni /mcp 401.

Metadati risorsa protetta RFC 9728 per /api.

Un’autorizzazione app connessa in sospeso per la pagina di consenso: nome e dominio del client come dichiarati nei metadati (mai scaricato un logo), se è un client registrato, host di redirect, e livello di accesso e capacità richiesti. Autorizzazioni sconosciute, scadute o risolte sono not_found.

Approva un’app connessa per uno dei progetti della persona dopo una prova fresca (tipo oauth_authorization_approval, soggetto l’id autorizzazione): crea l’identità agente dell’app (tipo agente mcp_client, la persona responsabile), la sua appartenenza e la sua concessione con l’accesso scelto (leggi o gestisci; omesso mantiene il livello richiesto, che di default è leggi) e le capacità (un sottoinsieme di quelle richieste), e risponde con redirect_uri, portando codice, stato e iss, a cui la pagina naviga.

Il codice è valido per 60 secondi. Un membro limitato agli schermi non collega agenti, non emette credenziali e non gestisce le persone del progetto: outside_screen_scope (chiedi al proprietario del progetto).

Nega un’app connessa dopo una prova recente (tipo oauth_authorization_denial) e risponde con il redirect_uri, che riporta error=access_denied, state e iss, verso cui la pagina naviga. Un membro limitato agli schermi non collega agenti, non emette credenziali e non gestisce le persone del progetto: outside_screen_scope (chiedi al proprietario del progetto).