# Actions

These are a collection of endpoints that allow you to mint new, interact with, and view your existing Canarytokens.

# List Kinds of Canarytokens

TIP

The values returned by this Canarytokens API correspond to the kind parameter used to create Canarytokens. As an example, if you wanted to create a Cloned Web Canarytoken, you would check the response to this Canarytokens API and use cloned-web to define the Canarytoken type you wish to create.

GET /api/v1/canarytokens/list

Lists the available Canarytokens on your Canary Console.

Required Parameters

auth_token string

A valid auth token

Response

A JSON structure with result indicator and Canarytokens information.

Example

Response

{
  "canarytokens": {
      "active-directory-login": "Active Directory Login",
      "autoreg-google-docs": "Google Doc",
      "autoreg-google-sheets": "Google Sheet",
      "aws-id": "AWS API Key",
      "aws-s3": "AWS S3 Bucket",
      "azure-entra-login": "Azure Entra Login",
      "azure-id": "Azure Login Certificate and Config",
      "cloned-css": "CSS cloned site",
      "cloned-web": "Cloned Website",
      "credit-card": "Credit Card",
      "dns": "DNS",
      "doc-msexcel": "MS Excel Document",
      "doc-msword": "MS Word Document",
      "fast-redirect": "Fast Redirect",
      "gmail": "Gmail",
      "google-docs": "Google Doc",
      "google-sheets": "Google Sheet",
      "http": "Web Bug",
      "msexcel-macro": "MS Excel Macro Document",
      "msword-macro": "MS Word Macro Document",
      "mysql-dump": "MySQL Dump File",
      "office365mail": "Office 365 Mail Bug",
      "pdf-acrobat-reader": "Acrobat PDF",
      "pwa": "Fake App",
      "qr-code": "QR Code",
      "sensitive-cmd": "Sensitive Command",
      "signed-exe": "Custom Exe/Binary",
      "slack-api": "Slack API Key",
      "slow-redirect": "Slow Redirect",
      "web-image": "Custom Web Image",
      "windows-dir": "Windows Folder",
      "wireguard": "WireGuard VPN",
  },
    "result": "success"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

# Credit Card Canarytoken Limit

GET /api/v1/canarytokens/limit/credit-card

Retrieve the Credit Card Canarytoken limit and the number of Credit Card Canarytokens still available on the Canary Console.

Required Parameters

auth_token string

A valid auth token

Response

A JSON structure containing the Credit Card Canarytoken kind, remaining token count, and token limit.

Example

Response

{
  "kind": "credit-card",
  "limit": 4,
  "remaining": 3,
  "result": "success"
}

1
2
3
4
5
6

# Paginate Canarytokens

GET /api/v1/canarytokens/paginate

Fetch a page of all your Canarytokens with a specified limit per page, as well as cursors that allow you to iterate through the remaining pages.

Required Parameters

auth_token string

A valid auth token

Optional Parameters

flock_id string

A valid flock_id (for returning Canarytokens for a specific Flock)

limit string

Defaults to: 10

Maximum value: 2500

The size of the pages

cursor string

A valid page cursor retrieved from the cursor element returned along with a page while doing pagination

Response

A JSON structure with the current page of Canarytokens and cursors pointing to your next and previous pages.

Example

Response

{
  "canarytokens": [
    {
      "access_key_id": "<aws_access_key_id>",
      "canarytoken": "<token_code>",
      "created": "1586249510.069870",
      "created_printable": "2020-04-07 08:51:50 (UTC)",
      "enabled": true,
      "factory_auth": "<factory_auth_token>",
      "flock_id": "flock:default",
      "hostname": "<token_hostname>",
      "key": "<token_key>",
      "kind": "aws-id",
      "memo": "Example Memo",
      "node_id": "<node_id>",
      "renders": {
        "aws-id": "\n    [default]\n    aws_access_key_id = <aws_access_key_id>\n    aws_secret_access_key = <aws_secret_access_key>"
      },
      "secret_access_key": "<aws_secret_access_key>",
      "triggered_count": 0,
      "updated_id": 17,
      "url": "<token_url>",
      "username": "<user_name>"
    },
    {
      "access_key_id": "<aws_access_key_id>",
      "canarytoken": "<token_code>",
      "created": "1586246956.323499",
      "created_printable": "2020-04-07 08:09:16 (UTC)",
      "enabled": true,
      "factory_auth": "<factory_auth_token>",
      "flock_id": "flock:default",
      "hostname": "<token_hostname>",
      "key": "<token_key>",
      "kind": "aws-id",
      "memo": "Example Memo",
      "node_id": "<node_id>",
      "renders": {
        "aws-id": "\n    [default]\n    aws_access_key_id = <aws_access_key_id>\n    aws_secret_access_key = <aws_secret_access_key>"
      },
      "secret_access_key": "<aws_secret_access_key>",
      "triggered_count": 4,
      "updated_id": 14,
      "url": "<token_url>",
      "username": "<user_name>"
    },
    {
      "canarytoken": "<token_code>",
      "cloned_web": "<cloned_domain>",
      "created": "1586183526.183108",
      "created_printable": "2020-04-06 14:32:06 (UTC)",
      "enabled": true,
      "flock_id": "flock:default",
      "hostname": "<token_hostname>",
      "key": "<token_key>",
      "kind": "cloned-web",
      "memo": "Cloned website detector on <cloned_domain>",
      "node_id": "<node_id>",
      "renders": {
        "cloned-web": "<script>\n    if (document.domain != \"<cloned_domain>\" && document.domain != \"<cloned_domain>\") {\n        var l = location.href;\n        var r = document.referrer;\n        var m = new Image();\n        m.src = \"<token_url>\" + encodeURI(l) + \"&r=\" + encodeURI(r);\n    }\n</script>"
      },
      "triggered_count": 0,
      "updated_id": 12,
      "url": "<token_url>"
    }
  ],
  "cursor": {
    "next": "MToxMjozOjQ6Mjo0",
    "next_link": "https://EXAMPLE.canary.tools/api/v1/canarytokens/paginate?cursor=MToxMjozOjQ6Mjo0&auth_token=EXAMPLE_AUTH_TOKEN",
    "prev": null,
    "prev_link": null
  },
  "page_num": 1,
  "page_total": 4,
  "result": "success"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76

# Create Canarytoken

POST /api/v1/canarytoken/create

Create a new Canarytoken.

Required Parameters

auth_token string

A valid auth token

kind string

Specifies the type of Canarytoken. Please check "List Canarytokens" for available Canarytoken kind values.

memo string

A reminder that will be included in the alert to let you know where you placed this Canarytoken, limited to 10000 characters.

Optional Parameters

aws_access_key string

AWS Access Key ID (required if automating creation of AWS S3 token)

aws_secret_key string

AWS Secret Access Key (required if automating creation of AWS S3 token)

aws_session_token string

AWS Session Token (required if automating creation of AWS S3 token, using temporary credentials)

aws_region string

AWS region (required if automating creation of AWS S3 token)

azure_id_cert_file_name string

Azure ID config will use this as the file path to the certificate (required when creating Azure ID tokens).

browser_redirect_url string

Browser redirect URL is the URL you want your Canarytoken server to redirect attackers to after they have triggered your Canarytoken token (required when creating fast-redirect and slow-redirect tokens)

browser_scanner_enabled boolean

Defaults to: true

Enables a Javascript scanner to retrieve more information (only valid with 'http' Canarytokens)

cloned_web string

Domain to check against (required when creating cloned-web tokens)

custom_domain string

Specifies the custom Canarytoken domain to use (that's already been linked to the Console) when creating a Canarytoken

expiry string

Specifies the expiry when creating a Canarytoken. String format using y, mo, w, d, h are supported. E.g. 12h, 6mo (Only AWS API Key token)

doc file

Upload MS Word Document to canarytoken; optionally used with MS Word Document (doc-msword) token. With curl use the following flag -F 'doc=@upload-me.docx; type=application/vnd.openxmlformats-officedocument.wordprocessingml.document'

exe file

The Windows executable that you would like tokened (required when creating signed-exe tokens)

expected_referrer string

The expected referrer to make a request when creating the Cloned CSS and Azure Entra Login Canarytokens.

flock_id string

Defaults to: 'flock:default' or flock_id of auth_token

A valid flock_id (defaults to the Default Flock or flock id of auth_token if using Canarytoken Deploy Flock API key type)

idp_app_type string

Type of the Fake App for the IdP App Canarytoken. Valid options are:

aws, azure, bitwarden, dropbox, duo, elasticsearch, freshbooks, gcloud, gdrive, github, gitlab, gmail, intune, jamf, jira, kibana, lastpass, ms365, msteams, onedrive, onepassword, outlook, pagerduty, sage, salesforce, sap, slack, virtru, zendesk, zoho, zoom

industry string

Defaults to: corporate

Name of Industry for MySQL Dump Canarytoken. Valid options are: corporate, consulting, education, financial, industrial, legal, medical, tech.

pdf file

Upload PDF file to canarytoken; optionally used with Adobe PDF canarytoken (pdf-acrobat-reader). With curl use the following flag -F pdf=@upload-me.pdf; type=application/pdf

process_name string

Name of the process you want to monitor (required when creating sensitive-cmd tokens)

pwa_app_name string

Name of the Fake App for the pwa Canarytoken

pwa_icon string

Name of the icon used by your Fake App for the pwa Canarytoken

s3_log_bucket string

S3 bucket where logs will be stored (required when creating aws-s3 tokens)

s3_source_bucket string

S3 bucket to monitor for access (required when creating aws-s3 tokens)

skip_create_if_exists string

Defaults to: false

When enabled, if a canarytoken exists with matching flock, memo, and kind then the existing token will be returned instead of creating a new token. This parameter only applies to a subset of token kinds, and for certain token kinds additional parameters are matched on. See how we match tokens.

tokened_usernames string

A comma separated list of Active Directory usernames to token (required when creating active-directory-login tokens)

web_image file

Upload an Image file (jpeg or png) that will be displayed on the Canarytokens URL (required when creating web-image tokens) With curl use the following flag: -F 'web_image=@upload-me.png; type=image/png' for png files -F 'web_image=@upload-me.jpg; type=image/jpeg' for jpeg files

Response

A JSON structure with the created Canarytoken information.

Example

Response

{
  "canarytoken": {
    "browser_scanner_enabled": true,
    "canarytoken": "<token_code>",
    "created": "1586161315.087693",
    "created_printable": "2020-04-06 08:21:55 (UTC)",
    "enabled": true,
    "flock_id": "flock:default",
    "hostname": "<token_hostname>",
    "key": "<token_key>",
    "kind": "http",
    "memo": "Example Memo",
    "triggered_count": 0,
    "updated_id": 7,
    "url": "<token_url>"
  },
  "result": "success"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# Delete Apeeper Canarytoken Factory

POST /api/v1/apeeperfactory/delete

Delete an Apeeper Canarytoken factory.

Required Parameters

auth_token string

A valid auth token

hash string

A valid ApeeperFactory hash

Response

A JSON structure with result indicator.

# Delete Canarytoken

POST /api/v1/canarytoken/delete

Delete a Canarytoken. You'll need to delete all incidents on a token before you can delete the token itself. If there are still incidents attached to the token, you can specify `clear_incidents=true` to delete them all.

Required Parameters

auth_token string

A valid auth token

canarytoken string

A valid Canarytoken

Optional Parameters

clear_incidents boolean

Delete associated incidents

Response

A JSON structure with result indicator.

Example

Response

{
  "result": "success"
}

1
2
3

# Bulk Delete Canarytokens

POST /api/v1/canarytokens/delete

Bulk delete Canarytokens that match the specified criterion. If clear_incidents is specified, all incidents on all tokens to be deleted will also be deleted. If clear_incidents is not specified or false and any incidents exist on matching tokens, no tokens will be deleted and an error returned.

Required Parameters

auth_token string

A valid auth token

domains string

A comma separated list of custom domains from which all tokens should be deleted.

Optional Parameters

clear_incidents boolean

If true, delete all incidents on all matching tokens before deleting matching tokens

Response

A JSON structure with result indicator.

Example

Response

{
  "result": "success",
  "deleted_count": 1
}

1
2
3
4

# Disable Canarytoken

POST /api/v1/canarytoken/disable

Disable a Canarytoken.

Required Parameters

auth_token string

A valid auth token

canarytoken string

A valid Canarytoken

Response

A JSON structure with result indicator.

Example

Response

{
  "result": "success"
}

1
2
3

# Download Canarytoken

GET /api/v1/canarytoken/download

Download the generated file (if one exists) for the supplied Canarytoken.

Required Parameters

auth_token string

A valid auth token

canarytoken string

An identifier for a Canarytoken that supports downloadable files

Response

A file if the Canarytoken supports file generation, otherwise an error.

Example

Response

$ ls -l
-rw-r--r--  1 user  thinkst  5095 Apr  7 12:29 <filename>

1
2

# Enable Canarytoken

POST /api/v1/canarytoken/enable

Enable a disabled Canarytoken.

Required Parameters

auth_token string

A valid auth token

canarytoken string

A valid Canarytoken

Response

A JSON structure with result indicator.

Example

Response

{
  "result": "success"
}

1
2
3

# Fetch a Canarytoken

GET /api/v1/canarytoken/fetch

Fetch information about a specific Canarytoken.

Required Parameters

auth_token string

A valid auth token

canarytoken string

A valid Canarytoken

Response

A JSON structure with the Canarytoken.

Example

Response

{
  "result": "success",
  "token": {
    "canarytoken": "<token_code>",
    "created": "1585947523.255526",
    "created_printable": "2020-04-03 20:58:43 (UTC)",
    "enabled": true,
    "flock_id": "flock:default",
    "hostname": "<token_hostname>",
    "key": "<token_key>",
    "kind": "dns",
    "memo": "Example Memo",
    "triggered_count": 0,
    "updated_id": 4,
    "url": "<token_url>"
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# Remove AWS S3 Canarytoken

POST /api/v1/canarytoken/remove/s3

Remove an AWS S3 Canarytoken from your Amazon console.

Required Parameters

auth_token string

A valid auth token

canarytoken string

A valid Canarytoken

aws_access_key string

AWS Access Key ID (this is not stored on the Console and is only used for the duration of the operation)

aws_secret_key string

AWS Secret Access Key (this is not stored on the Console and is only used for the duration of the operation)

aws_region string

AWS Region where the token is located

Optional Parameters

aws_session_token string

AWS Session Token. Required when using temporary AWS authentication (this is not stored on the Console and is only used for the duration of the operation)

delete_buckets boolean

Defaults to: false

Boolean indicating if buckets must be deleted

s3_source_bucket string

Name of the S3 bucket which was being monitored (required if delete_buckets is true)

Response

A JSON structure with result indicator.

Example

Response

{
  "result": "success"
}

1
2
3

# Update Canarytoken Memo

POST /api/v1/canarytoken/update

Update the memo of a Canarytoken.

Required Parameters

auth_token string

A valid auth token

canarytoken string

A valid Canarytoken

memo string

A reminder that will be included in the alert to let you know where you placed this Canarytoken, limited to 10000 characters.

Response

A JSON structure with result indicator.

Example

Response

{
  "result": "success",
  "token": {
    "canarytoken": "<token_code>",
    "created": "1585947523.255526",
    "created_printable": "2020-04-03 20:58:43 (UTC)",
    "enabled": true,
    "flock_id": "flock:default",
    "hostname": "<token_hostname>",
    "key": "<token_key>",
    "kind": "dns",
    "memo": "Updated Example Memo",
    "triggered_count": 0,
    "updated_id": 4,
    "url": "<token_url>"
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# Update Canarytoken Redirect URL

POST /api/v1/canarytoken/update/redirect_url

Update the redirect URL of a Canarytoken that supports redirects.

Required Parameters

auth_token string

A valid auth token

canarytoken string

A valid Canarytoken that supports redirects (e.g. slow redirect token or QR code token)

redirect_url string

A valid url that the user should be redirected to after opening the Canarytoken

Response

A JSON structure with result indicator.

Example

Response

{
  "result": "success",
  "token": {
    "browser_redirect_url": "https://example.com",
    "browser_scanner_enabled": false,
    "canarytoken": "<token_code>",
    "created": "1774610690.455351",
    "created_printable": "2026-03-27 11:24:50 (UTC)",
    "enabled": true,
    "flock_id": "flock:default",
    "hostname": "<token_hostname>",
    "key": "<token_key>",
    "kind": "fast-redirect",
    "kind_description": "Fast Redirect",
    "memo": "Example Memo",
    "triggered_count": 0,
    "updated_id": 6,
    "canarytoken": "<token_url>"
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# Remove Canarytoken Redirect URL

POST /api/v1/canarytoken/remove/redirect_url

Remove the redirect URL of a Canarytoken that supports optional redirects.

Required Parameters

auth_token string

A valid auth token

canarytoken string

A valid Canarytoken that supports optional redirects (e.g. QR code token)

Response

A JSON structure with result indicator.

Example

Response

{
  "result": "success",
  "token": {
    "browser_redirect_url": "",
    "browser_scanner_enabled": false,
    "canarytoken": "<token_code>",
    "created": "1776168497.972660",
    "created_printable": "2026-04-14 12:08:17 (UTC)",
    "enabled": true,
    "flock_id": "flock:default",
    "hostname": "<token_hostname>",
    "key": "<token_key>",
    "kind": "qr-code",
    "kind_description": "QR Code",
    "memo": "Example Memo",
    "qr_code": "<qr_code>",
    "triggered_count": 0,
    "updated_id": 11,
    "canarytoken": "<token_url>"
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

← Mass Deployment Cloned Web Ignore List →