# Queries
These are a collection of endpoints that allow you to query and view your Canarytokens.
Endpoints
# All Canarytokens
TIP
This will return all your Canarytokens in a single list. This may cause issues if you have many Canarytokens minted on your Console. A cleaner option is to use Search Canarytokens or Paginate Canarytokens as they will paginate the results and allow you to cycle through them.
GET /api/v1/canarytokens/fetch
Fetch all created Canarytokens.
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)
include_endpoints string
Include factory endpoints (such as ApeeperFactory)
Response
A JSON structure with list of all Canarytokens.
Example
curl https://EXAMPLE.canary.tools/api/v1/canarytokens/fetch \ -d auth_token=EXAMPLE_AUTH_TOKEN \ -GCopied!
1
2
3
2
3
Response
{ "result": "success", "tokens": [ { "browser_scanner_enabled": true, "canarytoken": "<token_code>", "created": "1585947447.092035", "created_printable": "2020-04-03 20:57:27 (UTC)", "enabled": false, "flock_id": "flock:default", "hostname": "<token_hostname>", "key": "<token_key>", "kind": "http", "memo": "Example Memo", "node_id": "<node_id>", "triggered_count": 0, "updated_id": 2, "url": "<token_url>" }, ... ] }Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# 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
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
curl https://EXAMPLE.canary.tools/api/v1/canarytokens/paginate \ -d auth_token=EXAMPLE_AUTH_TOKEN \ -d limit=3 -GCopied!
1
2
3
4
2
3
4
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" }Copied!
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
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
# Search Canarytokens
GET /api/v1/canarytokens/search
Search through all Canarytokens using optional search filters. Results will be paginated.
Required Parameters
auth_token string
A valid auth token
Optional Parameters
flock_id string
A valid flock_id
search_string string
A search string to filter on. This is a word-delimited prefix search on the canarytoken ID and memo fields.
kind string
A valid Canarytoken kind to filter for a specific kind
active boolean
If set to True, only return active tokens. If set to False, only return inactive tokens. (not setting this returns all tokens)
limit string
Defaults to: 10
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 filtered Canarytokens and cursors pointing to your next and previous pages.
Example
curl https://EXAMPLE.canary.tools/api/v1/canarytokens/search \ -d auth_token=EXAMPLE_AUTH_TOKEN \ -d search_string=EXAMPLE \ -GCopied!
1
2
3
4
2
3
4
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>\n aws_secret_access_key = <aws_secret_access_key>" }, "secret_access_key": "<aws_secret_access_key>", "triggered_count": 0, "unacked_alert_count": 0, "updated_id": 17, "url": "<token_url>", "username": "<user_name>" }, { "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", "node_id": "<node_id>", "triggered_count": 0, "unacked_alert_count": 0, "updated_id": 4, "url": "<token_url>" }, { "browser_scanner_enabled": true, "canarytoken": "<token_code>", "created": "1585947447.092035", "created_printable": "2020-04-03 20:57:27 (UTC)", "enabled": false, "flock_id": "flock:default", "hostname": "<token_hostname>", "key": "<token_key>", "kind": "http", "memo": "Example Memo", "node_id": "<node_id>", "triggered_count": 0, "unacked_alert_count": 0, "updated_id": 2, "url": "<token_url>" } ], "cursor": { "next": null, "next_link": null, "prev": null, "prev_link": null }, "page_number": 1, "result": "success", "total_pages": 1, "total_results": 3 }Copied!
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
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