Vai al contenuto
Sursa Developers

POST/oauth/token

Emettere un token OAuth 2.0

oauth_token

L’endpoint del token OAuth 2.0 (RFC 6749, sezione 3.2). grant_type: authorization_code scambia un codice monouso con una coppia di token e richiede code_verifier (PKCE S256); refresh_token emette una nuova coppia per un token di aggiornamento e invalida il token di aggiornamento precedente (rotazione), e il riutilizzo di uno invalidato revoca l’intera catena; client_credentials emette un token per conto dell’organizzazione, solo per un’app confidential, senza token di aggiornamento. Un client confidential si autentica con l’intestazione Authorization: Basic o con i campi client_id e client_secret; un client pubblico invia solo client_id. Un token di accesso è valido per 1 ora, un token di aggiornamento per 90 giorni. Risposte ed errori seguono la RFC 6749, sezione 5, con Cache-Control: no-store. Aggiunto nella 1.62.0.

Autenticazione

Non servono credenziali.

Corpo della richiesta

application/x-www-form-urlencoded

Oggetto: OAuthTokenRequest

  • grant_typestringobbligatorio

    Valori ammessi: authorization_coderefresh_tokenclient_credentials

  • codestring

    Codice di autorizzazione (authorization_code).

  • redirect_uristring

    Lo stesso URI di reindirizzamento della richiesta di autorizzazione (authorization_code).

  • code_verifierstring

    Il valore PKCE originale, da 43 a 128 caratteri (authorization_code).

  • refresh_tokenstring

    Token di aggiornamento (refresh_token).

  • scopestring

    Ambiti separati da spazi, solo per restringere (refresh_token, client_credentials).

  • client_idstring

    ID dell’app, quando il segreto non viene passato nell’intestazione Authorization: Basic.

  • client_secretstring

    Segreto client di un’app confidential, quando non viene passato nell’intestazione Authorization: Basic.

Risposte

200I token sono stati emessi.

Intestazioni della risposta

  • RateLimit-Policy

    Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.

  • RateLimit

    Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).

  • X-RateLimit-Remaining

    Richieste rimanenti nel limite più restrittivo.

  • X-RateLimit-Reset

    Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: OAuthTokenResponse

  • access_tokenstringobbligatorio

    Token di accesso (kbat_…) per l’intestazione Authorization: Bearer.

  • token_typestringobbligatorio

    Valori ammessi: Bearer

  • expires_inintegerobbligatorio

    Durata del token di accesso in secondi.

  • refresh_tokenstring

    Token di aggiornamento (kbrt_…); assente per client credentials.

  • scopestringobbligatorio

    Ambiti del token separati da spazi.

400Errore come definito nella RFC 6749, sezione 5.2.

Intestazioni della risposta

  • RateLimit-Policy

    Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.

  • RateLimit

    Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).

  • X-RateLimit-Remaining

    Richieste rimanenti nel limite più restrittivo.

  • X-RateLimit-Reset

    Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: OAuthErrorResponse

401Credenziali del client non valide (`invalid_client`).

Intestazioni della risposta

  • RateLimit-Policy

    Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.

  • RateLimit

    Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).

  • X-RateLimit-Remaining

    Richieste rimanenti nel limite più restrittivo.

  • X-RateLimit-Reset

    Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: OAuthErrorResponse

Nuovi tentativi sicuri

Invia un’intestazione Idempotency-Key (per esempio un UUID) con ogni POST e PATCH. Un nuovo tentativo con la stessa chiave entro 24 ore restituisce la risposta salvata invece di eseguire di nuovo la richiesta.

Limiti di frequenza

Le risposte contengono le intestazioni RateLimit e RateLimit-Policy e le precedenti X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Una risposta 429 contiene Retry-After in secondi: attendi e riprova.

← oauth · Riferimento API