{"revision":"9f11a31dd2951db0","language":"it","entry":{"id":"oidc-token","kind":"endpoint","group":"oidc","title":"Scambia un codice o un refresh token","method":"POST","path":"/oidc/token","paths":[],"summary":"L'endpoint dei token: il codice con il verificatore PKCE, o un refresh token, per un token di accesso, un token ID e un nuovo refresh token.","response":"{access_token, token_type: Bearer, expires_in: 600, refresh_token?, id_token, scope}.","parameters":[],"sample":"/oidc/token","access":"private-code","base":"directory","notes":["Gli errori di questo endpoint seguono OAuth: `{\"error\", \"error_description\"}` (RFC 6749, 5.2), non l'oggetto `error` del resto delle API. Un limite risponde comunque 429 con la busta solita.","application/x-www-form-urlencoded, al più 16 KiB, ogni parametro una volta. Un'app confidenziale usa l'autenticazione Basic.","Qui non si legge nessuna chiave API: un'intestazione Authorization su /oidc/ è la credenziale dell'app o della persona."],"errors":["400 invalid_grant","400 invalid_request","400 invalid_scope","400 unsupported_grant_type","401 invalid_client","404 invalid_request","429 rate_limited","500 internal_error","503 busy"],"related":["sign-in-with-veil"],"sections":[{"kind":"code","language":"shell","code":"curl -fsS -u \"$CLIENT_ID:$CLIENT_SECRET\" \\\n  -d grant_type=authorization_code -d code=\"$CODE\" -d code_verifier=\"$VERIFIER\" \\\n  --data-urlencode redirect_uri=https://app.example.org/callback \"https://veil.rip/oidc/token\""}],"live":false,"responses":[{"status":200,"contentType":"application/json","description":"{access_token, token_type: Bearer, expires_in: 600, refresh_token?, id_token, scope}.","fields":[{"name":"access_token","type":"string","description":"Opaco, veil_at_…, 10 minuti. Conservato solo come hash."},{"name":"token_type","type":"string","description":"Bearer."},{"name":"expires_in","type":"integer","description":"600."},{"name":"refresh_token","type":"string","description":"veil_rt_…, 30 giorni, ruotato a ogni uso, al più 90 giorni dall'accesso. Manca per un'app senza refresh."},{"name":"id_token","type":"string","description":"JWT firmato con l'algoritmo dell'app (EdDSA o ES256), kid nell'intestazione."},{"name":"scope","type":"string","description":"Gli scope concessi."}]}],"responseObjects":[],"errorFormat":"json","errorDetails":[{"status":400,"code":"invalid_grant","description":"Errore OAuth: il codice o il refresh token non è valido, è scaduto, usato, revocato o di un'altra app, oppure il verificatore PKCE non torna. Un codice o un refresh token usato due volte chiude tutti i token del suo accesso.","action":"Ricomincia l'accesso. Non riprovare mai un codice.","scope":"endpoint"},{"status":400,"code":"invalid_request","description":"Errore OAuth: un parametro manca, è ripetuto o malformato, oppure il corpo non è un modulo.","action":"Leggi `error_description`, correggi la richiesta e mandala di nuovo.","scope":"endpoint"},{"status":400,"code":"invalid_scope","description":"Errore OAuth: un refresh ha chiesto uno scope che l'accesso non ha concesso, o ha tolto openid.","action":"Tieni o restringi gli scope, con openid. Uno scope nuovo vuole un nuovo accesso.","scope":"endpoint"},{"status":400,"code":"unsupported_grant_type","description":"Errore OAuth: grant_type non è authorization_code né refresh_token.","action":"Usa uno dei due tipi.","scope":"endpoint"},{"status":401,"code":"invalid_client","description":"Errore OAuth: l'app non si è autenticata con il metodo che ha registrato.","action":"Controlla client id e segreto (Basic), l'asserzione (private_key_jwt, un jti nuovo ogni volta) o client_id per un'app pubblica.","scope":"endpoint"},{"status":404,"code":"invalid_request","description":"Errore OAuth: Accedi con Veil non è configurato su questo server.","action":"Usa https://veil.rip, o un server il cui documento di discovery risponde.","scope":"endpoint"},{"status":429,"code":"rate_limited","description":"È stato superato un limite anonimo, delle richieste firmate o della chiave API.","action":"Attendi almeno i secondi indicati da `Retry-After`. Condividi coda e budget dei tentativi tra i tuoi processi.","scope":"common"},{"status":500,"code":"internal_error","description":"Si è verificato un errore imprevisto del server. I dettagli interni non vengono restituiti.","action":"Riprova le letture con attese crescenti e un limite. Controlla l’esito delle scritture prima di inviare una nuova operazione firmata.","scope":"common"},{"status":503,"code":"busy","description":"L’applicazione ha raggiunto un limite temporaneo di concorrenza o del database.","action":"Attendi i secondi indicati da `Retry-After` e riprova con attese crescenti e un limite.","scope":"common"}],"responseHeaders":[{"name":"Content-Type","value":"application/json","description":"JSON, anche per gli errori."},{"name":"Cache-Control","value":"no-store","description":"Privata: mai in una cache."},{"name":"Pragma","value":"no-cache","description":"RFC 6749, 5.1."}],"bodyFields":[{"name":"grant_type","in":"body","required":true,"description":"authorization_code o refresh_token."},{"name":"code","in":"body","required":false,"description":"Il codice (authorization_code)."},{"name":"redirect_uri","in":"body","required":false,"description":"Lo stesso della richiesta (authorization_code)."},{"name":"code_verifier","in":"body","required":false,"description":"Il verificatore PKCE, da 43 a 128 caratteri (authorization_code)."},{"name":"refresh_token","in":"body","required":false,"description":"Il refresh token (refresh_token)."},{"name":"scope","in":"body","required":false,"description":"Un refresh può restringere gli scope."},{"name":"client_id","in":"body","required":false,"description":"Un'app pubblica si nomina qui."},{"name":"client_assertion, client_assertion_type","in":"body","required":false,"description":"private_key_jwt (RFC 7523): un JWT firmato da una chiave del jwks dell'app, aud l'issuer o questo endpoint, exp entro 5 minuti, un jti nuovo."}],"verify":"Nel token ID controlla la firma con la chiave del JWKS che il suo kid nomina, iss, aud e azp (il tuo client_id), exp e nonce. Con lo scope veil si può controllare anche veil_consent: vedi la guida.","documentationUrl":"https://veil.rip/docs/oidc-token?lang=it","supportsBrowserFetch":false,"browserMode":"local-or-server"}}