Autenticazione

Le API 2026-09 usano OAuth2: la tua integrazione scambia le credenziali dell’App con un token temporaneo e lo invia in ogni chiamata.

Creare l’App

Apri la pagina API App

Dal pannello vai in Impostazioni → API App (OAuth2).

Crea l’App

La pagina mostra Client ID, Client Secret e l’Endpoint della tua piattaforma, insieme ai due comandi di esempio già compilati con i tuoi dati.

Conserva le credenziali

Copia Client ID e Client Secret nella configurazione del tuo software, come variabili d’ambiente o in un gestore di segreti. Non inserirle nel codice sorgente e non condividerle.

Pagina API App con Client ID, Client Secret ed Endpoint

Ogni utente può avere una sola App attiva. Con Revoca App l’App viene disattivata in qualsiasi momento: i token già emessi smettono subito di funzionare. Se sospetti che il secret sia stato esposto, revoca l’App e creane una nuova.

Richiedere il token


curl -X POST https://<sottodominio>.spedisci.online/oauth/token \
    -d "grant_type=client_credentials" \
    -d "client_id=<client_id>" \
    -d "client_secret=<client_secret>" \
    -d "scope=client-api"

Risposta:


{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOi..."
}

Campo	Significato
`access_token`	Il token da inviare nelle chiamate
`expires_in`	Durata in secondi: 3600, cioè un’ora
`scope`	Deve essere `client-api`: un token senza questo scope viene rifiutato

Il token agisce a nome del proprietario dell’App: tutte le risorse sono quelle del suo cliente.

Usare il token

Invia il token nell’header Authorization di ogni chiamata:


curl https://<sottodominio>.spedisci.online/api/2026-09/credit \
    -H "Authorization: Bearer <access_token>" \
    -H "Accept: application/json"

Rinnovo del token

Il token scade dopo un’ora e non ha un refresh token: alla scadenza richiedine uno nuovo con le stesse credenziali.

Non richiedere un token a ogni chiamata. Conserva il token in memoria, riutilizzalo fino a pochi minuti prima della scadenza e richiedine uno nuovo solo allora, oppure quando una chiamata risponde 401.

Revocare un token


curl -X POST https://<sottodominio>.spedisci.online/api/2026-09/logout \
    -H "Authorization: Bearer <access_token>"

Risposta: { "revoked": true }. Viene revocato solo il token usato nella chiamata; gli altri token restano validi.

Errori di autenticazione

HTTP	`code`	Causa
401	`unauthenticated`	Token mancante, scaduto o revocato
403	`insufficient_scope`	Il token non ha lo scope `client-api`
403	`account_disabled`	L’utente o il cliente non è attivo
403	`client_role_required`	L’utente non ha il ruolo cliente

Il formato completo degli errori è descritto in Formato delle risposte ed errori.