Quickstart · 2 minutes
From API key to first block
Shield has two front doors onto the same three layers — deterministic rules, an LLM analyzer, and a sanitizer. The proxy is OpenAI-compatible: change one base URL and an app you already have is covered. POST /canaryshield/inspect scores a single string and hands you the verdict, which is what you need for everything that is not a chat completion. Steps 2 and 3 set up one each; you want both.
1. Get an API key
Product API requests authenticate with a workspace API key sent in the X-API-Key header. Mint one in the app: Settings → API keys → Generate API key. Every plan can, Free included; keys are not a paid feature. The full key appears once, on that screen, and is not recoverable afterwards — copy it before you navigate away and keep it server-side. Five active keys per account.
Revoke a leaked key from the same card while it is still on screen: the server identifies a key from the key itself, and there is no list-keys endpoint to recover one you have lost. Sealed evidence written with a revoked key stays valid.
2. Point your chat client at the proxy
Your provider key stays in api_key and is forwarded upstream unchanged — CanaryVaults identity travels only in the X-API-Key header. The default upstream is api.openai.com; send X-Upstream-Base-URL: https://api.groq.com to proxy Groq instead. Streaming is not supported yet — set stream=False.
Two boundaries before you build on this. The proxy serves POST /v1/chat/completions and no other route, so client.models.list(), embeddings, the Responses API and Assistants all 404 against this base URL — keep an unproxied client for those. And it inspects only messages with role: "user": a tool result, an assistant turn or a system prompt reaches your model unread. Step 3 is how you cover those.
Blocked requests return an OpenAI-shaped error naming the attack class and confidence. The block itself is recorded as an ordinary row in your Shield log — original message, attack type, confidence, explanation, timestamp — with no content hash, and it is readable only by you at GET /canaryshield/blocks/{user_id}. Shield does not produce verifiable evidence today: a block never reaches the audit trail, so there is nothing for the public verifier to resolve.
If you need an evidenced record of a block, write one yourself with POST /canaryaudit/log — that call returns a content_hash a third party can check. Audit writes are metered and the Free allowance is zero, so this path needs a paid plan.
3. Score what the proxy cannot see
POST /canaryshield/inspect runs the same three layers over one string you choose. No base URL, no upstream allowlist, no route restriction: it scores a tool result, a retrieved chunk, a system prompt, an assistant turn, or a user message headed for a model the proxy cannot reach. user_id is your own workspace UUID and has to match the authenticated caller, or the call is a 403.
A clean message comes back with the same six keys, blocked false and sanitized_message holding the text to pass on — the sanitizer may have removed a span, so forward that value and not your original. Add system_prompt to score the message against the instructions it is trying to override, and history to judge an attack staged across turns. An inspection spends the same monthly unit a proxied completion does, and a detection is logged and alerted the same way.