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

Apri il pannello SmartCQ del tuo tenant.
Vai su Impostazioni → API Keys.
Clicca + Nuova API key.
Inserisci un nome che ti aiuti a riconoscerla (es. "CRM produzione", "Script import notturno").
Seleziona gli scope che vuoi concedere (vedi scope sotto).
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`

Scope CRM, Pratica e Documenti arriveranno con i rispettivi moduli.

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

Rate limit

Ogni API key ha un rate limit di 60 richieste al minuto (window scorrevole, in-memory).

Su ogni risposta SmartCQ aggiunge gli header standard:

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.