> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Thinkst Canary

> Connect your Thinkst Canary console to Serval so workflows can list and manage Canary devices, triage and acknowledge incidents, create and manage Canarytokens, organize flocks, and administer console users.

## About Thinkst Canary

[Thinkst Canary](https://canary.tools) 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

| Capability        | Description                                                                                                                                                                                                                                               |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Device management | List all, live, or dead Canaries, filter devices, read device info and IPs, reboot or update a device, manage device notes, and handle the commissioning lifecycle (list pending, commission, assign pending, cancel, decommission).                      |
| Incident triage   | List all, acknowledged, or unacknowledged incidents, search incidents by string, logtype, or time window, fetch a single incident, look up incident history for a source IP, and acknowledge, unacknowledge, or delete incidents individually or in bulk. |
| Canarytokens      | List available token kinds, fetch, paginate, and search existing tokens, create new Canarytokens of any kind, enable, disable, or delete a token, and update a token's memo.                                                                              |
| Flock management  | List flocks and their summaries, filter flocks, list a flock's devices, users, and settings, create, rename, or delete flocks, move devices between flocks, and assign flock managers and watchers.                                                       |
| User management   | List and filter console users, fetch a user, add, edit, enable, disable, or remove users, change access levels, assign or unassign users to flocks, and trigger password resets.                                                                          |
| Console resources | Ping the API, read detailed license info, and fetch the console audit trail.                                                                                                                                                                              |
| Raw API access    | A flexible "Thinkst Canary API request" action covering every endpoint in the curated Canary Console v1 API surface.                                                                                                                                      |

The full endpoint list is documented in the [Canary API docs](https://docs.canary.tools/guide/list-of-endpoints.html).

## Get your credentials

Serval needs your console's **subdomain** and an **API auth token**.

<Steps>
  <Step title="Open your Canary console settings">
    Sign in to your console at `https://YOURDOMAIN.canary.tools` and go to **Settings > Global Settings > API**.
  </Step>

  <Step title="Enable the API (if needed)">
    If API access is disabled on the console, enable it - all API calls fail while it is off.
  </Step>

  <Step title="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).
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Connect Thinkst Canary to Serval

<Steps>
  <Step title="Open the connect catalog">
    In Serval, add a new connection and choose **Thinkst Canary** (shown with a Beta label).
  </Step>

  <Step title="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.
  </Step>

  <Step title="Paste the API auth token">
    Paste the auth token you created on the console's API settings page.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Tip>
  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.
</Tip>

## 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

<AccordionGroup>
  <Accordion title="The console domain is the bare subdomain, not a URL">
    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.
  </Accordion>

  <Accordion title="API key roles are fixed at creation">
    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.
  </Accordion>

  <Accordion title="API access can be disabled console-wide">
    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.
  </Accordion>

  <Accordion title="File and download endpoints are not included">
    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.
  </Accordion>

  <Accordion title="The integration is marked Beta">
    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.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Thinkst Canary integration.