Overview:
Step 1: Sign in to your Console
Step 4: Gather API Credentials and Test Connection
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
Note: We also maintain a Python wrapper for the API. The documentation for the Python wrapper is hosted 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
-
Click the Gear Icon.
-
Select Global Settings.
Step 3: Enable the API
-
Click API in the menu.
-
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
-
Domain Hash
is the unique hash identifying your Console when using the API. -
Default API Key
is the specific key we are going to use. -
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.