Autenticazione

Ogni richiesta all'API di Certivant si autentica con una chiave API — un token bearer di lunga durata, limitato a una singola organizzazione. Sessioni e cookie servono alla dashboard; l'API non li usa mai.

Formato dell'intestazione

Authorization: Bearer ck_live_NjV3aXJWN0RpZ2tRZ1JLWEcxc1V2eEgwUjg...

• Il nome dell'intestazione è Authorization.
• Lo schema è Bearer (uno spazio, poi la chiave).
• La chiave inizia con ck_live_ (produzione) o ck_test_ (test). Le chiavi precedenti che iniziano con kyk_ continuano a funzionare senza modifiche.

Ogni risposta di un endpoint autenticato con chiave riporta X-Certivant-Environment: live|test. Le chiavi di test servono solo a contrassegnare l'utilizzo; non isolano i dati (vedi Chiavi di produzione e di test).

Se la chiave manca, è sconosciuta, revocata, scaduta o ruotata, Certivant risponde con HTTP 401 e error.code = "UNAUTHORIZED". error.reason è un sotto-codice stabile:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "reason": "api_key_expired",
    "message": "This API key has expired. Create or rotate a key."
  }
}

Da dove provengono le chiavi

Le chiavi API si creano nella dashboard in KYC → Sviluppatore. Deve essere Proprietario o Amministratore dell'organizzazione. La chiave viene mostrata una sola volta, subito dopo la creazione: Certivant conserva solo un hash SHA-256, quindi non possiamo mostrarla di nuovo. Se la perde, la revochi e ne crei una nuova.

La dashboard elenca ogni chiave (tramite i suoi primi 8 caratteri) insieme ai relativi ambiti, al momento dell'ultimo utilizzo e al numero di utilizzi. Può revocare una chiave in qualsiasi momento; la revoca è immediata e irreversibile.

Ambiti

Gli ambiti sono additivi. Può concedere qualsiasi sottoinsieme alla creazione di una chiave. Una richiesta a un endpoint il cui ambito richiesto non possiede restituisce HTTP 403 con error.code = "FORBIDDEN" e error.reason = "insufficient_scope"; il messaggio elenca tutti gli ambiti che sarebbero stati accettati.

Ambiti standard

Ambiti per risorsa

Per il minimo privilegio può concedere invece ambiti <risorsa>:<azione>. Ciascuno è accettato sugli endpoint della propria risorsa in aggiunta all'ambito standard corrispondente, e non va mai oltre quella risorsa.

Esempi: forms:write consente a una chiave di eseguire POST /v1/kyc/forms/:formId/send ma non di creare richieste di verifica; verifications:read + analytics:read è una chiave di sola lettura per una dashboard. <risorsa>:manage include ogni altra azione su quella risorsa.

Restrizioni

Oltre agli ambiti, una chiave può essere limitata quando la crea o la modifica:

• Moduli — la chiave può usare solo i moduli che sceglie, e raggiungere solo le verifiche create tramite essi. Vedi Limitazione ai moduli.
• Workflow — la chiave può attivare solo i workflow di automazione (per nome) che sceglie. Vedi Limitazione ai workflow.
• Lista IP consentiti — indirizzi IPv4/IPv6 e intervalli CIDR (203.0.113.7, 198.51.100.0/24, 2001:db8::/32). Una richiesta da qualsiasi altro indirizzo — o il cui indirizzo non può essere determinato — viene rifiutata con 403 ip_not_allowed.
• Scadenza — dopo expiresAt la chiave restituisce 401 api_key_expired.

Tutte le restrizioni sono vuote (quindi senza limiti) per impostazione predefinita, e le chiavi esistenti non ne hanno. Le chiavi create prima che esistessero le restrizioni (kyk_…) e i token del connettore non vengono mai limitati.

Limitazione ai moduli

Una chiave limitata ai moduli X e Y è confinata a tali moduli e alle verifiche create tramite essi. Una verifica è "creata tramite un modulo" quando è stata inviata con POST /v1/kyc/forms/:formId/send (da qualsiasi chiave o dalla dashboard), inviata tramite il link pubblico del modulo, oppure creata con POST /v1/kyc/requests e un formId.

Un rinnovo, o una verifica UBO generata da una verifica aziendale, appartiene allo stesso modulo della verifica da cui deriva.

Limitazione ai workflow

Certivant non ha un endpoint che indichi un workflow per nome, quindi questa restrizione non produce un 403 su nessuna chiamata. Controlla quali workflow di automazione possono essere eseguiti per le verifiche create dalla chiave:

• Ogni verifica creata dalla chiave (POST /v1/kyc/requests, /requests/batch, POST /v1/kyc/forms/:formId/send, POST /v1/kyc/conferences con un richiedente inline) registra la chiave da cui proviene.
• Da quel momento, per quella sola verifica, possono essere eseguiti solo i workflow il cui nome è nell'elenco della chiave — qualunque cosa generi l'evento: il richiedente che invia il modulo, una decisione, un revisore, un webhook o la chiave stessa. Le esecuzioni basate su eventi di qualsiasi altro workflow vengono saltate, così come un workflow avviato da un altro workflow tramite lo step Trigger workflow.
• L'elenco attuale della chiave si applica finché la chiave esiste, quindi restringere o rimuovere la restrizione ha effetto immediato sulle verifiche in corso. Se la chiave viene eliminata, continua ad applicarsi l'elenco che aveva al momento della creazione della verifica.
• Le verifiche create dalla dashboard, da un richiedente su un modulo pubblico, o da una chiave senza limitazione ai workflow non sono interessate, né lo è alcun altro trigger (pianificazioni, altre verifiche).
• Un rinnovo e le verifiche UBO di un'azienda ereditano la restrizione della verifica da cui derivano.

Il motivo di errore workflow_not_allowed è riservato agli endpoint che ricevono un workflow per nome; al momento non ne esiste nessuno.

Chiavi di produzione e di test

Le chiavi ck_live_… servono alla produzione, le chiavi ck_test_… allo sviluppo e alla CI. L'ambiente è un'etichetta, non una sandbox: le risposte riportano X-Certivant-Environment, la dashboard mostra il badge e le voci di audit registrano il prefisso della chiave — ma una chiave di test legge e scrive gli stessi dati di una chiave di produzione. L'unica sandbox è quella a livello di tenant: finché Certivant non ha verificato la Sua organizzazione, le funzioni di verifica dal vivo sono bloccate per ogni chiave. Usi un'organizzazione separata se vuole dati di test completamente separati.

Igiene consigliata degli ambienti

• Una chiave per ambiente. Crei chiavi separate per local, staging e production. Se viene compromesso un ambiente, gli altri due restano al sicuro.
• Etichetti le chiavi in modo descrittivo. payments-service-prod-2026Q2 è meglio di key1. L'etichetta compare nel registro di audit.
• Imposti una scadenza sulle chiavi che servono solo temporaneamente — per migrazioni, demo o accessi di terze parti. Certivant rifiuta automaticamente la chiave quando expiresAt è passato.
• Ruoti ogni anno. Crei una nuova chiave, passi il Suo servizio a quella nuova e revochi la vecchia quando la nuova ha gestito il traffico senza errori.
• Non committi mai le chiavi in git. Usi il Suo gestore di segreti — AWS Secrets Manager, GCP Secret Manager, Doppler, Infisical o, come minimo, file .env inseriti nel .gitignore.

Rotazione senza interruzioni

Usi Ruota chiave sulla chiave (Sviluppatore → Chiavi API), oppure l'API:

POST /api/kyc/api-keys/{id}/rotate        (dashboard session, api.access permission)
{ "overlapHours": 24 }

sequenceDiagram
  participant You
  participant Dashboard
  participant Service
  participant Certivant
  You->>Dashboard: Rotate key (overlap 24 h)
  Dashboard-->>You: ck_live_new_… (same scopes, restrictions, IP allowlist)
  You->>Service: Deploy with new key in env var
  Service->>Certivant: Authenticated requests with new key
  Note over Certivant: Old key still works until the overlap ends
  Certivant-->>Service: Old key → 401 api_key_rotated after the overlap

1. Ruoti la chiave. La sostituta copia etichetta, ambiti, restrizioni, lista IP consentiti e scadenza; il suo valore completo viene mostrato una sola volta.
2. Distribuisca il Suo servizio con la nuova chiave durante la sovrapposizione (da 0 a 168 ore, predefinita 24). La vecchia chiave continua a funzionare fino ad allora, e il suo campo Ultimo utilizzo nella dashboard mostra se qualcosa la chiama ancora.
3. Al termine della sovrapposizione la vecchia chiave restituisce 401 api_key_rotated. Usi overlapHours: 0 per revocarla subito. Può anche revocarla prima, manualmente.

Cosa succede quando una chiave viene revocata

La richiesta successiva che usa la chiave revocata restituisce 401. Non c'è alcun periodo di tolleranza. Se revoca per errore una chiave ancora necessaria, ne crei una nuova — una revoca non si può annullare.

Endpoint pubblici (nessuna chiave richiesta)

Un piccolo insieme di endpoint è intenzionalmente pubblico — non richiede una chiave API:

• GET /api/health e GET /api/status — sonde operative.
• GET /api/branding — configurazione di branding pubblica per l'interfaccia ospitata.
• GET /api/kyc/public/status?ref=… — consultazione dello stato del richiedente tramite riferimento esterno.
• GET /api/kyc/public/forms/:slug e gli endpoint di invio dei moduli — usati dall'interfaccia ospitata dei moduli.

Sono documentati per completezza, ma la maggior parte delle integrazioni non li chiama mai direttamente: è la sessione ospitata a gestire tutte le interazioni pubbliche.

Registro di audit

Ogni chiamata API autenticata viene registrata in KycAuditLog con il prefisso della chiave chiamante, l'endpoint e il tipo di attore (api). Può consultare la traccia in KYC → Registro di audit nella dashboard. Le voci di audit vengono conservate per tutta la durata della richiesta a cui si riferiscono.