Surface 01 · CanaryVaults
Decoy identities
A decoy is a monitored email identity that CanaryVaults generates and owns. Decoys attach to a protected email address on your account, not to a file: adding a protected email mints three decoys for it, one in each tier — SOCIAL_MEDIA, EMAIL_ACCOUNT and FINANCIAL_LURE. The tier decides how loudly a hit is escalated.
You do not place decoys yourself. CanaryVaults seeds them onto the surfaces where stolen credentials get traded, on a delay after they are minted, and watches them from then on. A decoy address is unique and belongs to no real person, so contact with one is unambiguous: somebody harvested it.
Listing your decoys
GET /api/canaries authenticates with a Supabase session JWT, not with an API key. An X-API-Key header on its own returns 401. If you send both, the key owner must be the same user as the token or the request is rejected with 403.
Which makes this one a browser-side route in practice. The session token belongs to the web app: it is held in memory and its durable half is an HttpOnly cookie, so there is no supported way to lift one into a shell. A workspace key minted at Settings → API keys opens CanaryShield, CanaryRAG, CanaryHoneypot, CanaryAudit and CanaryAgent on any plan, Free included — it does not open this route. Read the block below as the shape the app receives, not as a call to paste.
The response is an object carrying a canaries array and a count, not a bare array. Decoys are created with status ACTIVE, which changes as a decoy is rotated or burned after a hit.
How many you get
Decoy count follows protected emails at three decoys per email. Free covers one protected email, Shield covers three, and Pro covers ten. There is no endpoint for minting a single decoy on its own.
When one fires
A hit produces a threat event carrying the attacker infrastructure fingerprint — IP, country, city, network operator, classification and abuse score — together with the tier-derived alert level and the age of the decoy in days. That is what reaches your alert channels. See Alerts & webhooks for delivery.
The alert does not carry an evidence hash. A threat event gets its SHA-256 content hash when the record is read back through the dashboard or the threat log, so look for the hash on the record rather than in the notification.