Applicazioni private

Le applicazioni private consentono di accedere alle API di Riseact tramite un token statico senza dover implementare il flusso OAuth. Sono adatte per script di automazione, integrazioni backend-to-backend e strumenti interni dove non è presente un utente umano che effettua il login.

Creare un'applicazione privata

1. Accedi al pannello di amministrazione della tua organizzazione Riseact.
2. Vai su Impostazioni → App → Applicazioni private.
3. Clicca su Nuova applicazione privata.
4. Assegna un nome descrittivo (es. "Sync CRM", "Export notturno").
5. Seleziona i permessi che vuoi concedere all'applicazione (vedi la sezione permessi di seguito).
6. Clicca su Crea.

Dopo la creazione, verrà mostrato il token di accesso. Copialo e conservalo in modo sicuro: non verrà mostrato di nuovo. Il token è associato all'organizzazione corrente e non scade.

caution

Tratta il token come una password. Non includerlo mai in codice versionato o in variabili d'ambiente esposte pubblicamente.

Usare il token

Il token va incluso in ogni richiesta come header HTTP Authorization:

Authorization: Bearer <IL_TUO_TOKEN>

L'header è identico sia per le API GraphQL che per le API REST.

GraphQL

curl -X POST https://core.riseact.org/admin/graphql/ \
  -H "Authorization: Bearer IL_TUO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "query { organization { name domain } }"}'

REST

curl https://core.riseact.org/api/v1/supporters/ \
  -H "Authorization: Bearer IL_TUO_TOKEN"

Le API REST supportano parametri di paginazione e ordinamento standard. Per maggiori dettagli, consulta la Guida alla paginazione REST.

Permessi

Ogni applicazione privata accede solo alle risorse per cui ha ricevuto esplicita autorizzazione al momento della creazione. I permessi seguono il formato entità:azione.

Permesso	Descrizione
supporter:read	Lettura dei sostenitori
supporter:write	Creazione e modifica dei sostenitori
supporter:export	Esportazione dei sostenitori
donation:read	Lettura delle donazioni
donation:write	Creazione e modifica delle donazioni
donation:export	Esportazione delle donazioni
payment:read	Lettura dei pagamenti
payment:write	Creazione e modifica dei pagamenti
campaign:read	Lettura delle campagne
campaign:write	Creazione e modifica delle campagne
project:read	Lettura dei progetti
project:write	Creazione e modifica dei progetti
activity:read	Lettura delle attività
activity:write	Creazione e modifica delle attività
reports:read	Accesso ai report
application:read	Lettura delle applicazioni installate
application:install	Installazione di applicazioni
sitefront:themes	Gestione dei temi del sito
sitefront:themes.code	Modifica del codice dei temi
sitefront:content	Gestione dei contenuti del sito
sitefront:navigation	Gestione della navigazione del sito
dbox:read	Lettura delle donation box
dbox:write	Creazione e modifica delle donation box

Come vengono verificati i permessi

Ogni operazione API richiede uno o più permessi specifici. Quando una richiesta arriva con il token, il sistema verifica che i permessi concessi all'applicazione includano quelli richiesti dall'operazione. Se il controllo fallisce, la risposta è un errore di autorizzazione.

I permessi di tipo :write non includono implicitamente il :read corrispondente: se la tua applicazione deve sia leggere che scrivere i sostenitori, seleziona entrambi supporter:read e supporter:write.

Rigenerare il token

Se il token viene compromesso, puoi rigenerarlo dalla stessa pagina di amministrazione (Impostazioni → App → Applicazioni private). La rigenerazione invalida immediatamente il token precedente.

Differenza rispetto alle partner app

Caratteristica	Applicazione privata	Partner app
Accesso	Singola organizzazione	Tutte le org che installano l'app
Autenticazione	Token statico, nessuna scadenza	OAuth 2.0 con PKCE, token temporanei
Gestione token	Manuale da admin	Automatica tramite refresh token
Caso d'uso tipico	Automazioni interne, script	Integrazioni di terze parti