Description: Enabling the API allows you to automate Canary Configs, Manage Alerts, Mass Create Canarytokens, and much much more (without even having to log in to your Console)! This covers API keys constrained to a specific flock. For API Keys with global access across the Console, see the Global API Keys.
- 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 Flock API key, you'll need to chose its type:
- Read-Only API keys can only view data in its flock,
- Analyst API keys can view data and also acknowledge, unacknowledged and delete alerts in its flock,
- Admin API keys has full privileges and can execute any API operation on its flock.
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 and an Admin key by folks responsible for managing the Console and birds.
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.
Note: We also maintain a Python wrapper for the API. The documentation for the Python wrapper is hosted here.
Follow the steps below to enable the API and generate an API token:
Step 1:
Log in to your Console.
Step 2:
Select the flock you wish to create a new API Key for.
Note: We selected "Cape Town - Office"
Step 3:
Once in the Flock, click on the Gear Icon at the top right of the Flock tab.
Step 4:
- Click on the Flock API Keys Tab.
- Click on the + symbol to add an API key.
Step 5:
- Choose the API key type, you have a choice of either Read-Only, Analyst or Admin.
- Add in a Name.
Step 6:
You will see a new API Key has been created.
Click on the Key and you will be presented with the Flock API Key details.
Auth Token is the API key that you'll need to use in order to make calls to your API.
Domain Hash is the unique hash identifying your Console when using the API.
Note: 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
You are able to grab your Console Domain hash from the URL at the top left of the page.
That's it, you're done ;-)