Scambia un codice o un refresh token

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.

POST/oidc/token

Accesso: Serve un codice privato
Client: Client locale o server

Corpo JSON#

Nome	Posizione	Significato
`grant_type`Obbligatorio	JSON	authorization_code o refresh_token.
`code`	JSON	Il codice (authorization_code).
`redirect_uri`	JSON	Lo stesso della richiesta (authorization_code).
`code_verifier`	JSON	Il verificatore PKCE, da 43 a 128 caratteri (authorization_code).
`refresh_token`	JSON	Il refresh token (refresh_token).
`scope`	JSON	Un refresh può restringere gli scope.
`client_id`	JSON	Un'app pubblica si nomina qui.
`client_assertion, client_assertion_type`	JSON	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.

Esempi di richiesta#

cURL

curl -fsS -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=authorization_code -d code="$CODE" -d code_verifier="$VERIFIER" \
  --data-urlencode redirect_uri=https://app.example.org/callback "https://veil.rip/oidc/token"

Risposta#

HTTP 200application/json

{access_token, token_type: Bearer, expires_in: 600, refresh_token?, id_token, scope}.

Campo	Tipo	Significato
`access_token`	`string`	Opaco, veil_at_…, 10 minuti. Conservato solo come hash.
`token_type`	`string`	Bearer.
`expires_in`	`integer`	600.
`refresh_token`	`string`	veil_rt_…, 30 giorni, ruotato a ogni uso, al più 90 giorni dall'accesso. Manca per un'app senza refresh.
`id_token`	`string`	JWT firmato con l'algoritmo dell'app (EdDSA o ES256), kid nell'intestazione.
`scope`	`string`	Gli scope concessi.

Intestazioni della risposta#

Intestazione	Valore	Significato
`Content-Type`	`application/json`	JSON, anche per gli errori.
`Cache-Control`	`no-store`	Privata: mai in una cache.
`Pragma`	`no-cache`	RFC 6749, 5.1.

Cosa verificare#

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.

Note d’uso#

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.

Errori#

Gli errori API restituiscono un oggetto error. Usa error.code nella logica del programma; error.message è un testo inglese per le persone e può cambiare. Guida a risposte ed errori

HTTP	Codice	Significato e cosa fare
400	`invalid_grant`	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. Ricomincia l'accesso. Non riprovare mai un codice.
400	`invalid_request`	Errore OAuth: un parametro manca, è ripetuto o malformato, oppure il corpo non è un modulo. Leggi `error_description`, correggi la richiesta e mandala di nuovo.
400	`invalid_scope`	Errore OAuth: un refresh ha chiesto uno scope che l'accesso non ha concesso, o ha tolto openid. Tieni o restringi gli scope, con openid. Uno scope nuovo vuole un nuovo accesso.
400	`unsupported_grant_type`	Errore OAuth: grant_type non è authorization_code né refresh_token. Usa uno dei due tipi.
401	`invalid_client`	Errore OAuth: l'app non si è autenticata con il metodo che ha registrato. Controlla client id e segreto (Basic), l'asserzione (private_key_jwt, un jti nuovo ogni volta) o client_id per un'app pubblica.
404	`invalid_request`	Errore OAuth: Accedi con Veil non è configurato su questo server. Usa https://veil.rip, o un server il cui documento di discovery risponde.

Errori comuni delle richieste

HTTP Codice Significato e cosa fare

429

HTTP	Codice	Significato e cosa fare
429	`rate_limited`	È stato superato un limite anonimo, delle richieste firmate o della chiave API. Attendi almeno i secondi indicati da `Retry-After`. Condividi coda e budget dei tentativi tra i tuoi processi.
500	`internal_error`	Si è verificato un errore imprevisto del server. I dettagli interni non vengono restituiti. Riprova le letture con attese crescenti e un limite. Controlla l’esito delle scritture prima di inviare una nuova operazione firmata.
503	`busy`	L’applicazione ha raggiunto un limite temporaneo di concorrenza o del database. Attendi i secondi indicati da `Retry-After` e riprova con attese crescenti e un limite.

rate_limited

È stato superato un limite anonimo, delle richieste firmate o della chiave API.

Attendi almeno i secondi indicati da Retry-After. Condividi coda e budget dei tentativi tra i tuoi processi.

500

internal_error

Si è verificato un errore imprevisto del server. I dettagli interni non vengono restituiti.

Riprova le letture con attese crescenti e un limite. Controlla l’esito delle scritture prima di inviare una nuova operazione firmata.

503

busy

L’applicazione ha raggiunto un limite temporaneo di concorrenza o del database.

Attendi i secondi indicati da Retry-After e riprova con attese crescenti e un limite.

Leggi questa voce in JSON