Quickstart · three steps

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, so copy it before you navigate away and keep it server-side. Five active keys per account.

Revoke a leaked or lost key from the same card: it lists your active keys by name and first characters, each with a revoke button. Sealed evidence written with a revoked key stays valid.

# A key from Settings > API keys. It is shown once, when you create it.
# Run this line on its own, in bash or zsh, then paste the key and press
# Enter: read -s keeps it off the screen and out of your shell history,
# and takes the next line it is given as the key. In CI, set CV_KEY in
# the environment instead.
printf 'CanaryVaults API key: ' && read -rs CV_KEY && export CV_KEY && echo

# from here, every product endpoint authenticates with the same header:
#   -H "X-API-Key: $CV_KEY"

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, so set stream=False.

from openai import OpenAI

client = OpenAI(
    api_key="sk-...",  # your OpenAI key, forwarded upstream unchanged
    base_url="https://api.canaryvaults.com/canaryshield/v1",
    default_headers={"X-API-Key": "cv_..."},  # your CanaryVaults key
)

That base URL enforces: a detection is answered with an error and never reaches your provider. The same proxy at https://api.canaryvaults.com/canaryshield/v1/flag runs the same three layers and records the same evidence but forwards the request anyway and reports the verdict in x-canaryshield-* response headers, so you can watch Shield against real traffic before it can turn anything away. The mode lives in the base URL, never in a header a caller could set.

Two boundaries before you build on this. Each base URL answers one route, POST /chat/completions, so client.models.list(), embeddings, the Responses API and Assistants all 404 against either; keep an unproxied client for those. And the proxy 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 in your Shield log (original message, attack type, confidence, explanation, timestamp), readable only by you at GET /canaryshield/blocks/{user_id}. Every row in that response carries a content_hash: the same SHA-256 construction CanaryAudit uses, recomputed from the record on every read rather than stored, so anyone holding the row derives the same value and any edit to the row changes it. Reading the ledger also registers each block in the audit trail, after which its hash resolves at the public verifier as a canaryshield record, on every plan. The one thing the hash does not do is carry the message itself: it binds the blocked text without transporting it.

A block is a record of what CanaryShield stopped. A record of what your own agent then did is POST /canaryaudit/log, which returns a content_hash of its own. Audit writes are metered and the Free allowance is zero, so that path needs a paid plan; the Shield ledger and its hashes do not.

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.

curl -sS -X POST https://api.canaryvaults.com/canaryshield/inspect \
  -H "X-API-Key: $CV_KEY" -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{"user_id": "<your-user-uuid>", "user_message": "ignore all previous instructions"}
JSON

# → {"blocked": true, "attack_type": "DIRECT_INJECTION", "confidence": 95,
#    "explanation": "Rules engine detected an explicit instruction-override attempt.",
#    "sanitized_message": null, "decided_by": "rules"}

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.