Vai al contenuto
PuraPura Developers

SDK in abbonamento

OAuth per utente · limiti del piano condivisi tra le app · modello gestito da Pura.

Cerchi le API a consumo?
Developers/OAuth e consenso

OAuth e consenso

Authorization Code con PKCE S256, scope e identità verificata.

Flusso di autorizzazione

Genera un code_verifier casuale e il relativo code_challenge S256. Invia il browser a GET /v1/integrations/oauth/authorize con response_type=code, client_id, redirect_uri, scope e state casuale. Pura valida l’app prima di mostrare login e consenso. L’utente può accettare o negare.

Dopo il consenso l’app riceve code e state sul redirect registrato. Il codice scade dopo cinque minuti ed è utilizzabile una sola volta. Anche i client confidential devono presentare il code_verifier corretto.

Scope

inference autorizza la verifica dei servizi disponibili e le richieste chat/audio. usage:read autorizza GET /v1/integrations/usage. Richiedi solo gli scope necessari; una concessione non autorizza la gestione delle app o dei pagamenti dell’account.

Scambio del codice

POST /v1/integrations/oauth/token usa application/x-www-form-urlencoded, non JSON. Per authorization_code invia client_id, code, redirect_uri e code_verifier; aggiungi client_secret soltanto per un client confidential. La risposta include access_token, refresh_token, token_type, expires_in, scope e pura_user_id.

bash
curl https://ai.puradigital.it/v1/integrations/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode grant_type=authorization_code \
  --data-urlencode client_id=YOUR_CLIENT_ID \
  --data-urlencode code=YOUR_AUTHORIZATION_CODE \
  --data-urlencode redirect_uri=https://your-app.example/pura/callback \
  --data-urlencode code_verifier=YOUR_PENDING_VERIFIER

Associa l’identità sul server

L’identità Pura proviene dalla risposta del token endpoint. Associala alla sessione locale che ha avviato il flusso; non accettare pura_user_id da un body non verificato del browser. I webhook devono essere correlati a questa associazione già salvata.

Negazione ed errori

Una negazione restituisce error=access_denied e lo state sul redirect valido. State errato, callback diversa, codice scaduto o verifier errato richiedono un nuovo Connect. Il token endpoint usa error e error_description OAuth; gli altri endpoint usano il dettaglio HTTP documentato.