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 session token, 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 authenticates to CanaryShield, CanaryRAG, CanaryHoneypot, CanaryAudit and CanaryAgent on any plan, Free included; what each call may then do is the plan's allowance, and Free's CanaryAudit write allowance is zero, so POST /canaryaudit/log answers 402 on Free while the reads and exports still work. The key does not open this route. Read the block below as the shape the app receives, not as a call to paste.

GET https://api.canaryvaults.com/api/canaries
Authorization: Bearer <the web app's own session token>

# → {
#     "canaries": [
#       {
#         "id": "8f1c…",
#         "canary_id": "mfx8k2p-a91ceb04",
#         "tier": 1,
#         "type": "SOCIAL_MEDIA",
#         "email": "james.miller.4f2a91.a91c@canaryvaults.com",
#         "status": "ACTIVE",
#         "created_at": "2026-08-21T09:14:02Z"
#       }
#     ],
#     "count": 1
#   }

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 decoy fires when an email reaches it. The hit becomes a threat event carrying the platform the email targeted (Unknown when CanaryVaults does not recognise one), the mail server that delivered it with its network operator and location, the tier-derived alert level and the age of the decoy in days. Your alert channels get the platform, the delivering server and the alert level. That server belongs to the sender's mail provider, not to the sender, so CanaryVaults names it as the delivering server and does not report it or share it. 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.