API

Your Console supports having multiple API keys (auth_token).

API keys are created with an Admin, Analyst or Read-Only role and a Note (or Name) to remind you of its purpose. These are fixed at creation. To change these, simply create a new API Key, rotate out the use of the old API Key, and delete the old API Key. Additionally a Key ID will be generated for each API Key that is used to help identify the key used in logs, and for use in key management endpoints.

Endpoints

POST /api/v1/settings/api/disable

POST /api/v1/settings/api/enable

POST /api/v1/auth_token/add

POST /api/v1/token/add DEPRECATED

GET /api/v1/auth_token/list

GET /api/v1/auth_token/download DEPRECATED

GET /api/v1/token/download DEPRECATED

DELETE /api/v1/auth_token/remove

DELETE /api/v1/token/remove DEPRECATED

Add a Global API key

POST /api/v1/auth_token/add

POST /api/v1/token/add DEPRECATED

Create a new Global API key.

Required Parameters

auth_token string

A valid auth token

auth_token_type string

The type of auth token to created. Either 'read-only', 'analyst' or 'admin'.

note string

A note for the Global API key on who/where it is used.

Response

JSON structure with the new Global API key.

Example

curl https://EXAMPLE.canary.tools/api/v1/auth_token/add \
  -d auth_token=EXAMPLE_AUTH_TOKEN -d auth_token_type=admin \
  -d note='Infrastructure Team'

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/auth_token/add'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'auth_token_type': 'admin',
  'note': 'Infrastructure Team'
}

r = requests.post(url, data=payload)

print(r.json())

Response

{
    "global_api_key": {
        "auth_token": "<auth_token>",
        "auth_token_type": "Admin",
        "created": "2023-04-13 19:12:15 UTC+0000",
        "created_by": "Global-API-Token[key_id:ffffffff]",
        "key_id": "<key_id>",
        "note": "Infrastructure Team"
    },
    "result": "success"
}

List the Global API Keys

GET /api/v1/auth_token/list

List the Global API Keys in use

Required Parameters

auth_token string

A valid auth token

Response

A JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/auth_token/list \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -G

import requests
import re

url = 'https://EXAMPLE.canary.tools/api/v1/auth_token/list'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN'
}

r = requests.get(url, params=payload)
filename = re.findall("filename=(.+)", r.headers["Content-Disposition"])[0]
with open(filename, 'wb') as f:
    f.write(r.content)

print(r.json())

Response

{
    "global_api_keys": [
        {
            "auth_token": "<auth_token>",
            "auth_token_type": "Admin",
            "created": "2023-04-13 19:12:15 UTC+0000",
            "created_by": "Global-API-Token[key_id:ffffffff]",
            "key_id": "<key_id>",
            "note": "Infrastructure Team"
        }
    ],
    "result": "success"
}

Delete a Global API key

DELETE /api/v1/auth_token/remove

DELETE /api/v1/token/remove DEPRECATED

Delete an existing Global API key.

Required Parameters

auth_token string

A valid auth token

key_id string

The key_id of Global API key to remove

Response

A JSON structure with result indicator.

Example

curl -X DELETE https://EXAMPLE.canary.tools/api/v1/auth_token/remove \
  -d auth_token=EXAMPLE_AUTH_TOKEN -d key_id=EXAMPLE_KEY_ID

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/auth_token/remove'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'key_id': 'EXAMPLE_KEY_ID'
}

r = requests.delete(url, data=payload)

print(r.json())

Response

{
  "result": "success"
}

Download the API Configuration File

GET /api/v1/auth_token/download DEPRECATED

GET /api/v1/token/download DEPRECATED

Download a Global API key configuration file for use by the Python API.

Required Parameters

auth_token string

A valid auth token

key_id string

The key_id of Global API key to download.

Response

File containing the API configuration.

Example

curl https://EXAMPLE.canary.tools/api/v1/auth_token/download \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -G -O -J

import requests
import re

url = 'https://EXAMPLE.canary.tools/api/v1/auth_token/download'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN'
}

r = requests.get(url, params=payload)
filename = re.findall("filename=(.+)", r.headers["Content-Disposition"])[0]
with open(filename, 'wb') as f:
    f.write(r.content)

print(r.json())

Response

{
  "result": "success"
}

Disable the API

POST /api/v1/settings/api/disable

Disable the Console API.

Required Parameters

auth_token string

A valid auth token

Response

JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/settings/api/disable \
  -d auth_token=EXAMPLE_AUTH_TOKEN

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/settings/api/disable'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN'
}

r = requests.post(url, data=payload)

print(r.json())

Response

{
  "result": "success"
}

Enable the API

TIP

If the API is not already enabled this can only be achieved by logging into the Console and enabling the setting from your Global Settings page.

POST /api/v1/settings/api/enable

Enable the Console API.

Required Parameters

auth_token string

A valid auth token

Response

JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/settings/api/enable \
  -d auth_token=EXAMPLE_AUTH_TOKEN

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/settings/api/enable'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN'
}

r = requests.post(url, data=payload)

print(r.json())

Response

{
  "result": "success"
}