# Canarytokens Settings

Apart from the Canarytokens section which allows you to create and manage Canarytokens, the following endpoints allow you to configure the Console-side settings for Canarytokens.

# Custom Webroot

Along with your Console, you have your own running Canarytokens server. This server runs on the <your_unique_hash>.o3n.io domain and is unique to your Canarytokens server. Any Canarytoken you create will reach out on this domain to trigger its alert.

We do however allow you to set a custom domain. This will mean that all new tokens will be create used the custom domain but will still reach out to your Console and create an alert if triggered.

Custom User Domain

In order for your Canarytokens to successfully reach out to your Console using your custom domain, you'll need to correctly setup the DNS records for the domain to point to your Console.

Assuming your custom domain is your.custom.domain and your Canarytokens server IP is x.x.x.x, an example configuration would require the below records to be setup in the your.custom.domain zone:

docs.your.custom.domain NS docs-ns.your.custom.domain
docs-ns.your.custom.domain A x.x.x.x
1
2

# Disable Custom User Domains

POST /api/v1/settings/canarytokens/user_domains/disable

Disable custom user domains for your Console.

Required Parameters

auth_token string
A valid auth token

Response

A JSON structure with result indicator.

Example

    Response
    {
      "result": "success"
    }
    
    1
    2
    3

    # Enable Custom User Domains

    POST /api/v1/settings/canarytokens/user_domains/enable

    Enable custom user domains for your Console.

    Required Parameters

    auth_token string
    A valid auth token

    Response

    A JSON structure with result indicator.

    Example

      Response
      {
        "result": "success"
      }
      
      1
      2
      3

      # Set Custom User Domains

      POST /api/v1/settings/canarytokens/user_domains/save

      Set the custom canarytokens domains for your Console.

      Required Parameters

      auth_token string
      A valid auth token
      user_domains string
      A newline separated list of custom domains to set

      Response

      A JSON structure with result indicator.

      Example

        Response
        {
          "result": "success"
        }
        
        1
        2
        3

        # Custom Site

        If someone browses to your Canarytokens domain (<your_unique_hash>.o3n.io), we'll present them with the default apache page (in order to not raise any alarms).

        This is usually sufficient (as you won't usually have people browsing to the site, only tokens getting triggered off the domain), but we do allow you to change it.

        # Disable Custom Canarytokens Site

        POST /api/v1/settings/canarytokens/webroot/disable

        Disable the custom Canarytokens site for your Console.

        Required Parameters

        auth_token string
        A valid auth token

        Response

        A JSON structure with result indicator.

        Example

          Response
          {
            "result": "success"
          }
          
          1
          2
          3

          # Enable Custom Canarytokens Site

          POST /api/v1/settings/canarytokens/webroot/enable

          Enable the custom Canarytokens site for your Console.

          Required Parameters

          auth_token string
          A valid auth token

          Response

          A JSON structure with result indicator.

          Example

            Response
            {
              "result": "success"
            }
            
            1
            2
            3

            # Set Custom Canarytokens Site

            POST /api/v1/settings/canarytokens/webroot/save

            Set the custom Canarytokens site for your Console.

            Required Parameters

            auth_token string
            A valid auth token
            webroot string
            Valid html of the site's page

            Response

            A JSON structure with result indicator.

            Example

              Response
              {
                "result": "success"
              }
              
              1
              2
              3