Developer FAQ
Developer FAQ
Distinct from the marketing /faq. Questions a dev hits while building against the gateway. For compliance and architecture-level questions, see /faq.
How do I rotate my API key?
Go to /account/dashboard, mint a new lcr_live_* key, deploy it to your apps, then revoke the old one. The dashboard supports overlapping keys so you have zero-downtime rollouts. Revocation is immediate — within a few seconds of clicking "revoke", the gateway returns 401 for any further requests with that key.
What's the difference between /v1/messages and /api/v1/proxy/messages?
/v1/messages is the Anthropic-SDK-shaped proxy: drop-in for the Anthropic SDK, just change base_url, and your existing code (model="claude-sonnet-4-6", messages=[...]) works unchanged. /api/v1/proxy/messages is the Lucairn-native shape: explicit per-field routing, multi-provider support (Claude / OpenAI / Gemini / Mistral / self-hosted), and proving-ground / compliance-trace flags. Both endpoints route through the same pipeline; pick the SDK-shaped one if you already use the Anthropic SDK, the native one if you want explicit control.
How do I verify a Lucairn Certificate offline?
A certificate is a self-contained Ed25519-signed payload. Pull the witness public key from /.well-known/veil-keys.json, reconstruct the canonical 7-key signable, and verify with any Ed25519 library. The Python and TypeScript SDKs ship a verify_certificate helper that does the canonical-bytes reconstruction for you. The signable schema is locked at protocol_version 2: changing the keys would break every verifier in the wild, so we only add metadata fields outside the signable.
What happens if the sanitizer is down?
The gateway fail-closes. You get HTTP 503 with {"error": "scanner_unavailable"}. This is intentional — silently passing un-sanitised payloads to the LLM would defeat the entire point. Watch /changelog for incident updates. The fail-closed behaviour is also why we recommend pinning the sanitizer image to the same release tag as the gateway.
How do I bring my own LLM key (BYOK)?
Pass your upstream provider key in the X-Upstream-Key header on every request. Free tier is BYOK only. Pro adds an option for shared upstream pools (we manage the key rotation). Enterprise can use customer-managed keys via your KMS. The X-Upstream-Key value is forwarded only to Sandbox B's outbound LLM call; the gateway never logs the value.
Can I self-host the gateway?
Yes. The Helm chart at deploy/helm/ runs on any Kubernetes 1.27+ cluster. The Compose stack (make compose-up) runs on a laptop. See /docs/deployment for the three deployment paths and the gotchas for each. Customers in healthcare, finance, and government deploy this way as standard.
Is there a streaming version of /v1/messages?
Not on the SDK-shaped endpoints today. /v1/messages (Anthropic shape) and /v1/chat/completions (OpenAI shape) both reject "stream": true with HTTP 400 streaming_not_supported — the per-chunk DLP-scan that would keep unsanitised tokens off the wire is still on the roadmap. The Lucairn-native /api/v1/proxy/messages endpoint can do SSE, but only when the operator sets STREAMING_ENABLED=true on the gateway (default deployments leave it off). Watch the changelog for the per-chunk DLP ship date; once it lands, streaming will be enabled across all three endpoints.
How do I see my usage / monthly token counts?
GET /api/v1/usage returns per-month token + request counts for your key. The dashboard at /account/dashboard renders the same data. Any authenticated tier can call GET /api/v1/account/audit for full request-level history with filters; CSV export of that audit history is Pro and Enterprise only.
What are the rate limits?
Free tier: 60 requests/min per key, 1200 requests/hour global on /api/v1/scan, fair-use on /v1/messages. Pro and Enterprise have per-tenant limits set during onboarding. The gateway returns 429 with a Retry-After header when you hit a limit. Limits are enforced at the gateway, not the upstream LLM, so they apply even if your Anthropic key has a higher quota.
How do I report a bug or get support?
Email [email protected] — usually a same-day response on weekdays. Bug reports with a request_id (visible in metadata.dsa_compliance.request_id) are easiest to triage. Security issues: [email protected]. Feature requests: link the relevant /roadmap item or open a discussion.
Where is the source code?
The Lucairn SDKs (@lucairn/sdk for JavaScript / TypeScript, lucairn for Python, @lucairn/mcp-server) are public on GitHub at github.com/Declade/lucairn-sdks. The gateway, sanitizer, and witness are private during the closed-launch period. Customers under NDA can request source-code access during evaluation.
What about GDPR Article 17 erasure?
Sandbox A exposes a dedicated DELETE /api/v1/identity/{id} endpoint that performs a hard delete with cascading cleanup. Once the identity is erased, all tokens linked to it become permanently non-resolvable — the historical entries in Sandbox B become genuinely anonymous. The deletion writes a signed erasure event to a separate append-only log alongside every actual delete, so auditors can verify the chain. See /faq for the compliance framing.
Related
Want to see this in action?
Book a working session — we'll walk through your use case together.