Canaries
REST endpoints for managing canary tokens.
REST surface for the canary registry. CLI equivalent: grith canary.
| Method | Path | Summary | Flags |
|---|---|---|---|
| GET | /canaries | List registered canary tokens. | |
| POST | /canaries | Add a new canary token. | |
| DELETE | /canaries/{id} | Remove a canary token. | |
| POST | /canaries/{id}/rotate | Rotate the canary value while keeping its identity. |
Canary shape
{
"id": "ca-7f1...",
"label": "aws-prod-decoy",
"format": "aws_secret",
"placed_at": "/home/you/.aws/credentials_backup",
"registered_at": "2026-05-10T11:00:00Z",
"fires": 0
}
The actual token value is never returned by the API — it would defeat the trap.
POST /canaries
Create + register a new canary. Request:
{
"format": "aws_secret",
"place": "/home/you/.aws/credentials_backup",
"label": "aws-prod-decoy"
}
For format: "custom", also include "value": "<literal token>".
Response: the canary shape (without the value).
POST /canaries/{id}/rotate
Generate a new token of the same format/label, replace the file in place, update the registration.
See also
Last updated: 2026-05-14Edit this page on GitHub →