Authentication

Factum Parse usa autenticazione tramite header X-API-Key — semplice, fail-closed e sicura contro side-channel.

Come funziona

Ogni richiesta agli endpoint business (/v1/uploads, /v1/uploads/{job_id}, /v1/parse) deve includere:

X-API-Key: <la-tua-chiave-api>

Se la chiave è assente o errata → 401 Unauthorized.

Fail-closed

• Chiave non configurata sul server → tutti gli endpoint business restituiscono 401. Il servizio è chiuso di default, mai aperto.
• FACTUM_API_KEY è la chiave primaria. Esiste un fallback ZYLA_PROXY_SECRET per la modalità “proxy” del marketplace Zyla.
• Il principio è identico a operator_api_key / RIZZO_PII_REQUIRED: se manca la configurazione, il servizio non espone dati.

Constant-time comparison

Il confronto con la chiave attesa usa secrets.compare_digest:

• nessuna side-channel timing (la durata del confronto non dipende dalla chiave);
• la chiave attesa non è mai confrontata con operatori non constant-time;
• il response body di un 401 non rivela se la chiave era solo “sbagliata” vs “formattata male”.

OpenAPI

Lo schema OpenAPI è generato automaticamente da FastAPI Security() e include:

securitySchemes:
  APIKeyHeader:
    type: apiKey
    in: header
    name: X-API-Key

Le tre route business sono marcate security: [{ APIKeyHeader: [] }].

Best practice client

• Tratta la chiave come un segreto: mai in URL, mai in log, mai nel frontend lato client pubblico.
• Il marketplace che la inietta a monte (Zyla Proxy) deve inoltrare un header X-API-Key corrispondente a FACTUM_API_KEY (o al ZYLA_PROXY_SECRET).