Registrazione delle app

Crea un’app nella console#

Accedi con un account Business e apri la gestione delle app nella console Pura, assegna un nome riconoscibile, carica l’icona PNG obbligatoria e registra da uno a dieci URI di callback. L’API POST /v1/integrations/apps richiede la sessione dell’account proprietario, non un token di inferenza.

curl https://ai.puradigital.it/v1/integrations/apps \
  -H "Authorization: Bearer $PURA_CONSOLE_TOKEN" \
  -F 'name=Example SaaS' \
  -F 'redirect_uris=["https://your-app.example/pura/callback","http://localhost:5173/auth/pura/callback"]' \
  -F 'confidential=true' \
  -F 'icon=@app-icon.png;type=image/png'

Immagine dell’app registrata#

L’icona è obbligatoria: file PNG non vuoto, massimo 2.000.000 byte (2 MB). Usa preferibilmente un’immagine quadrata, ad esempio 256×256 px; è consigliata una forma quadrata. L’immagine identifica l’app nell’elenco, nei collegamenti e nella schermata di consenso.

La registrazione accetta multipart/form-data con name, redirect_uris come array JSON, confidential e il file icon. In alternativa invia application/json con gli stessi metadati e icon_png_base64 contenente il PNG codificato in base64. La risposta include client_id, icon_url e client_secret (solo per app confidential). Risolvi icon_url rispetto all’origine dell’API Pura; l’immagine è servita come image/png da GET /v1/integrations/apps/{client_id}/icon.

Scegli il tipo di client#

Public: token_endpoint_auth_method=none, nessun secret, PKCE obbligatorio. Confidential: token_endpoint_auth_method=client_secret_post, secret inviato nel body form del token endpoint e custodito sul backend. Il secret viene restituito alla registrazione e alla rotazione; non è recuperabile dalla lista delle app.

Redirect e ambienti#

Il redirect deve corrispondere esattamente a un URI registrato, inclusi path e query. Schema, host, porta, path e query devono coincidere con la registrazione. Non sono ammessi wildcard, fragment o credenziali nell’URL; ogni URI può avere al massimo 2048 caratteri. Un URI sconosciuto non riceve nemmeno un redirect di errore: Pura restituisce l’errore direttamente.

Per il web in produzione usa HTTPS; per lo sviluppo locale puoi registrare http://localhost:5173/auth/pura/callback, http://127.0.0.1:5173/auth/pura/callback o un host che termina con .localhost. localhost e 127.0.0.1 sono URI distinti; le porte non sono intercambiabili. HTTP su host remoti o indirizzi LAN non è ammesso. Non condividere il client secret di produzione con ambienti di anteprima o codice consegnato al browser.

Deep link per app native#

Puoi registrare uno schema personalizzato, ad esempio myapp://oauth/callback oppure com.example.app:/oauth/callback. Lo schema deve iniziare con una lettera e può contenere lettere minuscole, cifre, +, . e -. Deve essere presente un host o un path. Se l’host contiene un punto, è rifiutato salvo gli host .localhost: usa quindi com.example.app:/oauth/callback, non com.example.app://oauth.example/callback.

Registra il gestore del deep link nel sistema operativo, avvia l’autorizzazione con createAuthorization e conserva pending nell’app che ha avviato il flusso. Quando il sistema consegna l’URI completo di ritorno, passalo a PuraOAuthClient.exchange(callbackUrl, pending) oppure all’equivalente Python. Usa un client pubblico con PKCE per un’app distribuita: non incorporare un client secret. Gli helper completeBrowserConnection e i componenti React sono per il ritorno nella stessa scheda del browser.

const options = {
  apiBase: 'https://ai.puradigital.it/v1',
  clientId: 'YOUR_REGISTERED_PUBLIC_CLIENT_ID',
};
const {url, pending} = await createAuthorization({
  ...options, redirectUri: 'myapp://oauth/callback',
});
// Retain pending in the initiating app; open url in the system browser.
// In your OS deep-link handler, after the callback is delivered:
const tokens = await new PuraOAuthClient(options).exchange(callbackUrl, pending);
await userTokenStore.set(tokens);

Callback, API e webhook sono URL diversi#

Il callback è l’indirizzo della tua app che riceve code e state: può essere HTTPS, HTTP loopback o deep link. apiBase è invece l’indirizzo dell’API Pura: https://ai.puradigital.it/v1. Non usare il callback come apiBase. I webhook richiedono un endpoint HTTPS pubblico raggiungibile da Pura: localhost e deep link non sono ricevitori webhook.

Rotazione e sospensione#

La rotazione invalida il precedente client secret senza revocare i grant esistenti. Conserva il nuovo secret nel secret store. La sospensione revoca i collegamenti dell’app e richiede una nuova autorizzazione degli utenti. Riattivare l’app non ripristina automaticamente i grant revocati.

Elimina un’app disabilitata#

La gestione delle app è riservata agli account Business. Disabilita l’app prima di eliminarla dalla console o tramite DELETE /v1/integrations/apps/{client_id}. Un’app attiva restituisce 409. L’eliminazione è definitiva e rimuove connessioni, credenziali OAuth, webhook e icona.