How does the API work?

How to use the Canary API to automate management of Canaries, alerts, and Canarytokens, enabling integration with scripts or applications, streamlining tasks without logging into the Console, and supporting both global and Flock-specific API keys.

Enabling the API allows you to change Canary Configs, Manage Alerts, Mass Create Canarytokens, Manage Users, Create Flocks, and much much more (without even having to log in to your Console)! This covers Global API keys which have Console-wide API access. For API access constrained to Flocks, see the Flock API keys.

Documentation & Scripts

• Our API documentation can be found here
• We also have a bunch of scripts we've written on our GitHub page here

API-Key Types

When creating a new Global API key, you'll need to choose its type:

• Read-Only API keys: Can only view data across the Console,
• Analyst API keys: Can view data across the Console and also acknowledge, unacknowledge, and delete alerts.
• Admin API keys: Have full privileges and can execute any API operation on the Console.

The Console supports the creation of multiple API Keys for easy key rotation and using separate keys for different operations. For instance:

• An Analyst key can be used by a SIEM to read and clear alerts.
• An Admin key can be used by folks responsible for managing the Console and birds.

Security note

Your Console and the API strictly support communicating using TLS 1.2 or higher. Attempting to query your Console with TLS 1.1 or lower will lead to a failure.

Follow the steps below to enable the API and generate an API token:

Step 1: Sign in to your Console

You can log in to your Console.

Step 2: Open Global Settings

1. Click the Gear Icon.

2. Select Global Settings.

Step 3: Enable the API

1. Click API in the menu.

2. Click Enable API.

Step 4: Gather API Credentials and Test Connection

You will need your Auth Token and Domain Hash when using the API — let's do a quick Ping Test to ensure everything is working — Ping Test found here

1. Domain Hash is the unique hash identifying your Console when using the API.
2. Default API Key is the specific key we are going to use.
3. Auth Token is the API key that you'll need to use in order to make calls to your API — you can use the copy option to copy the auth token.