Autenticazione

API key per-tenant, header Authorization, scope e rate limit.

Ogni richiesta verso l'API REST di SmartCQ deve includere un header Authorization con una API key valida del tenant proprietario dei dati.

Authorization: Bearer scq_<48hex>

Generare una API key

1. Apri il pannello SmartCQ del tuo tenant.
2. Vai su Impostazioni → API Keys.
3. Clicca + Nuova API key.
4. Inserisci un nome che ti aiuti a riconoscerla (es. "CRM produzione", "Script import notturno").
5. Seleziona gli scope che vuoi concedere (vedi scope sotto).
6. Conferma. La chiave in chiaro viene mostrata UNA SOLA VOLTA.

Importante — SmartCQ salva solo l'hash bcrypt della chiave, non il plaintext. Se la perdi, devi crearne una nuova: non c'è recupero possibile.

Salva la chiave in un gestore sicuro (1Password, Vault, variabile d'ambiente). Mai committarla in repository git, mai metterla in URL, mai esporla a un browser.

Format della chiave

• Prefisso fisso: scq_
• 48 caratteri esadecimali random
• Lunghezza totale: 52 caratteri

Esempio: scq_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

I primi 6 caratteri esadecimali dopo scq_ sono il prefix pubblico della chiave: SmartCQ li mostra in lista (es. scq_a1b2c3…) per aiutarti a identificare la chiave senza esporre il plaintext.

Scope

Lo scope è il principio del privilegio minimo applicato all'API. Una chiave con contacts:read può solo leggere contatti, non scriverli. Dai esattamente quello che serve al consumer, niente di più.

Scope	Permette
contacts:read	GET /contacts, GET /contacts/:id
contacts:write	POST /contacts, PATCH /contacts/:id (richiede anche read? no, è indipendente)
sends:read	GET /sends
campaigns:read	GET /campaigns/:id

Nota — Wildcard come contacts:* o * non sono supportati in v1. Ogni scope va elencato esplicitamente.

Ruolo della chiave

Oltre agli scope, ogni chiave ha un ruolo che decide cosa può fare l'azione. Lo scope abilita l'endpoint; il ruolo autorizza l'operazione. Si sceglie alla creazione:

Ruolo	Comportamento
Operativo (consigliato)	Legge e scrive i dati, nessuna operazione amministrativa.
Sola lettura	Nessuna scrittura, a prescindere dagli scope concessi.
Completo	Tutte le operazioni, anche quelle riservate al titolare.

Una chiave «Sola lettura» con scope contacts:write riceverà 403 insufficient_role sulle scritture: i due livelli si sommano, non si sostituiscono. Le chiavi create prima dell'introduzione del ruolo si comportano come «Completo» — il loro comportamento non è cambiato; se vuoi restringerle, creane una nuova col ruolo giusto e revoca la vecchia.

Rate limit

Ogni API key ha un limite di 60 richieste per finestra fissa di un minuto. Nella versione attuale il conteggio è mantenuto in memoria dall'istanza che gestisce la richiesta.

SmartCQ aggiunge gli header standard alle risposte riuscite e alla risposta 429:

x-ratelimit-limit: 60
x-ratelimit-remaining: 47
x-ratelimit-reset: 35

• x-ratelimit-limit: il limite per finestra
• x-ratelimit-remaining: richieste ancora disponibili in questa finestra
• x-ratelimit-reset: secondi al reset della finestra

Quando superi il limite ricevi 429 Too Many Requests con header Retry-After:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Limite di 60 richieste/minuto raggiunto. Riprova fra 35s."
  }
}

Revocare una chiave

In Impostazioni → API Keys puoi:

• Revocare una chiave: gli endpoint la rifiuteranno immediatamente con 401 invalid_key. La chiave resta in lista (audit) ma non è più riattivabile. Crea una nuova chiave per sostituirla.
• Eliminare una chiave: rimuove definitivamente la chiave dal listino. Operazione irreversibile.

Sicurezza — buone pratiche

• Una chiave per integrazione: se l'API key viene compromessa, sai esattamente cosa revocare senza impattare le altre integrazioni.
• Scope minimi: il consumer non dovrebbe avere più scope di quelli che usa davvero.
• Ruota periodicamente: ogni 6-12 mesi, soprattutto dopo cambi di personale.
• Variabile d'ambiente: la chiave va in .env, non hardcoded nel codice.
• Mai lato browser: l'API è server-side. Il rate limit per-key + assenza di CORS aperto rendono l'uso da browser inadatto e rischioso.
• Monitora lastUsedAt: in lista vedi quando ogni chiave è stata usata l'ultima volta. Una chiave "mai usata" da mesi va probabilmente cancellata.