OAuth e Original Connect

Original funziona come authorization server OAuth 2.0 / OpenID Connect. App esterne e piattaforme di agenti (ad esempio i client MCP) possono far accedere gli utenti con il loro account Original e agire per loro conto, tramite l'SDK Original Connect o un qualsiasi client OAuth standard.

Standard supportati

Standard	Cosa copre
RFC 6749	Framework OAuth 2.0 (grant authorization code e refresh token)
RFC 7636	PKCE, obbligatorio per tutti i client, solo S256
RFC 7591	Dynamic Client Registration: le app si registrano da sole, senza un admin
RFC 8414	Authorization Server Metadata (/.well-known/oauth-authorization-server)
OpenID Connect	ID token (RS256), discovery (/.well-known/openid-configuration), UserInfo
RFC 7009	Revoca dei token

Endpoint

Tutti gli endpoint sono relativi a https://ai.original.land.

Endpoint	Scopo
GET /.well-known/oauth-authorization-server	Metadati del server (usati dai client MCP)
GET /.well-known/openid-configuration	Stessi metadati, percorso OpenID Connect
POST /oauth/register	Registrazione dinamica del client
GET /oauth/authorize	Accesso e consenso dell'utente
POST /oauth/token	Scambio di un code o di un refresh token con i token
POST /oauth/revoke	Revoca di un refresh token
GET /oauth/userinfo	Profilo dell'utente autenticato
GET /oauth/jwks	Chiavi pubbliche per verificare ID token e access token

suggerimento

Parti dal documento di discovery. La maggior parte delle librerie OAuth ha bisogno solo dell'URL dell'issuer e configura il resto in automatico.

Registrare un client (RFC 7591)

Invia un body JSON a POST /oauth/register:

{
  "client_name": "My App",
  "redirect_uris": ["https://myapp.example.com/callback"],
  "token_endpoint_auth_method": "none",
  "grant_types": ["authorization_code", "refresh_token"],
  "scope": "openid profile agent.chat:<agentId>"
}

Campo	Note
client_name	Obbligatorio, massimo 200 caratteri
redirect_uris	Obbligatorio, da 1 a 20 URL. I redirect devono corrispondere esattamente
token_endpoint_auth_method	none (client pubblico, default) o client_secret_post (client confidenziale)
grant_types	Includi refresh_token per ricevere refresh token come client pubblico
scope	Separati da spazio. Gli scope non consentiti ai client dinamici vengono scartati
client_uri, logo_uri, contacts	Metadati opzionali

La risposta (201) contiene un client_id (prefisso oc_). I client confidenziali ricevono anche un client_secret (prefisso ocs_) che non scade.

warning

Il client_secret viene mostrato una sola volta nella risposta di registrazione. Conservalo in modo sicuro.

Le registrazioni hanno un limite di frequenza: una risposta 429 too_many_requests indica di riprovare più tardi.

Scope

Scope	Significato	Client dinamici
openid	Emette un ID token e abilita UserInfo	Sì
profile	Email, nome, immagine, piano e crediti	Sì
agent.chat:<agentId>	Chattare con un agente specifico per conto dell'utente	Sì
agent.purchase	Acquistare piani o riscattare voucher per gli agenti	Sì
workspace	Accesso privilegiato al workspace	No, richiede la registrazione manuale da parte del team Original

Se non viene richiesto alcuno scope, il client riceve openid profile.

Flusso di autorizzazione

1. Reindirizza l'utente a /oauth/authorize con response_type=code, client_id, redirect_uri, scope, state, nonce opzionale, code_challenge e code_challenge_method=S256.
2. L'utente accede, sceglie l'account e approva la schermata di consenso.
3. Original reindirizza a redirect_uri con code e state, oppure con error=access_denied se l'utente rifiuta.
4. Chiama POST /oauth/token (form-encoded) con grant_type=authorization_code, code, redirect_uri, client_id, code_verifier e client_secret per i client confidenziali.

Durata dei token

Token	Durata
Authorization code	60 secondi, uso singolo
Access token	1 ora
Refresh token (client confidenziale)	30 giorni
Refresh token (client pubblico)	7 giorni

I refresh token ruotano: ogni chiamata con grant_type=refresh_token restituisce un nuovo refresh token e invalida il precedente. I client pubblici ricevono refresh token solo se si sono registrati con il grant type refresh_token.

UserInfo

GET /oauth/userinfo con Authorization: Bearer <access_token> richiede lo scope openid. Con profile restituisce anche email, name, picture, il plan e i credits della piattaforma, gli agenti sbloccati e gli abbonamenti attivi agli agenti.