# Queries

These are a collection of endpoints that allow you to query and view your Canarytokens.

# 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

    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>"
        },
        ...
      ]
    }
    
    1
    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

      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

      # 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

        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
        }
        
        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