Authentication

How it works

Every request to business endpoints (/v1/uploads, /v1/uploads/{job_id}, /v1/parse) must include:

X-API-Key: <your-api-key>

If the key is missing or wrong → 401 Unauthorized.

Fail-closed

• No key configured on the server → all business endpoints return 401. The service is closed by default, never open.
• FACTUM_API_KEY is the primary key. A ZYLA_PROXY_SECRET fallback exists for Zyla marketplace “proxy” mode.
• The principle is identical to operator_api_key / RIZZO_PII_REQUIRED: if the configuration is missing, the service does not expose data.

Constant-time comparison

The comparison with the expected key uses secrets.compare_digest:

• No timing side-channel (comparison duration does not depend on the key);
• The expected key is never compared with non-constant-time operators;
• The 401 response body does not reveal whether the key was “wrong” vs “malformed”.

OpenAPI

The OpenAPI schema is auto-generated by FastAPI Security() and includes:

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

The three business routes are marked security: [{ APIKeyHeader: [] }].

Client best practices

• Treat the key as a secret: never in URL, never in logs, never in public client-side frontend.
• The upstream marketplace (Zyla Proxy) must forward an X-API-Key header matching FACTUM_API_KEY (or ZYLA_PROXY_SECRET).