Autenticazione

Panoramica

Le API utilizzano il protocollo OAuth 2.0 con il grant type password. Per autenticarti hai bisogno di:

Credenziale Descrizione
client_id UUID univoco fornito da Keliweb all'attivazione
client_secret Chiave segreta associata al client_id
username L'indirizzo email del tuo account Keliweb
password La password del tuo account Keliweb

{info} Le credenziali client_id e client_secret si trovano nella sezione Impostazioni → API dell'applicazione.

Flusso di autenticazione

Client                              Server
  |                                    |
  |-- POST /oauth/token (credenziali) -->|
  |<----------- access_token -----------|
  |<----------- refresh_token ----------|
  |                                    |
  |-- GET /api/invoices (Bearer token) ->|
  |<------------ risposta JSON ----------|
  |                                    |
  | (token scaduto dopo 1 ora)         |
  |                                    |
  |-- POST /oauth/token (refresh_token) >|
  |<----------- nuovo access_token -----|

Passo 1 — Ottenere il token

Chiama POST /oauth/token con le tue credenziali. Riceverai un access_token e un refresh_token. → Vedi Access Token

Passo 2 — Usare il token

Includi l'access_token nell'header Authorization di ogni richiesta:

Authorization: Bearer <access_token>

Passo 3 — Rinnovare il token

Prima della scadenza (o in caso di risposta 401), usa il refresh_token per ottenere un nuovo access_token senza reinserire le credenziali. → Vedi Refresh Token

Scadenza dei token

Token Durata Note
access_token 1 ora (3600s) Da rinnovare con il refresh_token alla scadenza
refresh_token 10 giorni Se scaduto, occorre ri-autenticarsi con le credenziali

{warning} Conserva i token in modo sicuro. Non esporli in codice client-side o repository pubblici.

Sicurezza

  • Tutte le chiamate avvengono esclusivamente su HTTPS.
  • In caso di risposta 401 Unauthorized, verifica che il token non sia scaduto e usa il flusso di refresh.
  • In caso di risposta 403 Forbidden, l'utente non dispone dei permessi necessari per quella risorsa.
  • Non condividere mai client_secret o password in codice versionato.

Response/Payload

Tutte le API Keliweb restituiscono sempre un payload JSON. In caso di errore di autenticazione, il formato della risposta è:

{
    "error": "invalid_credentials",
    "message": "The user credentials were incorrect.",
    "hint": "Check that you're using the correct username and password."
}