Skip to main content

​
About Thinkst Canary

Thinkst Canary is a deception platform: hardware, VM, and cloud “Canaries” plus Canarytokens act as tripwires that alert you the moment an attacker touches them. Connecting your Canary console to Serval lets workflows list and operate your Canary devices (Birds), triage incidents (search, acknowledge, delete), create and manage Canarytokens, organize devices into flocks, administer console users, and read the console audit trail and license state. Serval talks only to your own console’s address (for example abc123ef.canary.tools) and attaches your API auth token to every request as the X-Canary-Auth-Token header - workflow authors never see or handle the token. Authentication: API key (your Canary console’s subdomain plus an API auth token) Data sync: On-demand only. There is no background sync or scheduled polling - Serval calls the Canary API only when a workflow runs, and verifies the connection with lightweight read-only health checks.

​
What the Thinkst Canary integration enables

The full endpoint list is documented in the Canary API docs.

​
Get your credentials

Serval needs your console’s subdomain and an API auth token.
1

Open your Canary console settings

Sign in to your console at https://YOURDOMAIN.canary.tools and go to Settings > Global Settings > API.
2

Enable the API (if needed)

If API access is disabled on the console, enable it - all API calls fail while it is off.
3

Create an auth token

Add a new API key. Canary API keys are created with a fixed role - Admin, Analyst, or Read-Only - that cannot be changed later. Pick the least-privileged role that covers what your workflows will do (Read-Only is enough for listing devices, incidents, and tokens; managing devices, tokens, users, or acknowledging incidents needs a write-capable role).
4

Note your console domain

It’s the subdomain of your console URL: for https://abc123ef.canary.tools the console domain is abc123ef. It is also shown on the console’s Settings page.

​
Connect Thinkst Canary to Serval

1

Open the connect catalog

In Serval, add a new connection and choose Thinkst Canary (shown with a Beta label).
2

Enter the Console domain

Enter only the subdomain - abc123ef for abc123ef.canary.tools. Values containing .canary.tools, a scheme like https://, or uppercase letters are rejected.
3

Paste the API auth token

Paste the auth token you created on the console’s API settings page.
4

Save the connection

Serval builds your console’s address from the subdomain and runs the health checks below to confirm it can reach the Canary API with your token.
When you edit an existing connection, the stored token appears masked. Leave it as is to keep the existing token; to rotate it, replace the masked value with the entire new token.

​
Verifying the connection

The Thinkst Canary connection ships with four health checks. They also run again automatically whenever you save changes to the connection’s settings.
  • Validate Canary API connection - calls the ping endpoint. On failure, verify the console domain, that the auth token is valid, and that API access is enabled on the console.
  • List Canary devices - confirms the token can read the console’s devices, and reports how many were found.
  • List flocks - confirms the token can read flock summaries.
  • List Canarytokens - fetches a single page of Canarytokens to confirm token read access.

​
Gotchas and troubleshooting

Enter only the subdomain - abc123ef for abc123ef.canary.tools. Serval builds the full console address from it and only ever sends your token to your own console’s canary.tools subdomain.
A Canary API key’s role (Admin, Analyst, or Read-Only) cannot be changed after it is created. If workflows need to acknowledge incidents, manage tokens or devices, or administer users and the health checks pass but those actions fail, the stored key is likely Read-Only - create a new key with a write-capable role and rotate it into the connection.
Canary consoles can turn API access off entirely (Settings > Global Settings > API). If every call fails including ping, check that API access is enabled before suspecting the token.
Binary endpoints (token file downloads, VM image downloads, audit-trail JSON download) are excluded from the integration’s API surface - Serval’s JSON request path does not support file responses.
Thinkst Canary appears with a Beta label in the Serval connect catalog. Functionality described on this page is available today, but the integration’s surface may still evolve.
Need help? Contact support@serval.com for assistance with your Thinkst Canary integration.