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 to 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 created using 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.
Show details
Required Parameters auth_token string
A valid auth token
Response A JSON structure with result indicator.
Example curl https://EXAMPLE.canary.tools/api/v1/settings/canarytokens/user_domains/disable \
-d auth_token = EXAMPLE_AUTH_TOKEN
1 2
import requests
url = 'https://EXAMPLE.canary.tools/api/v1/settings/canarytokens/user_domains/disable'
payload = {
'auth_token' : 'EXAMPLE_AUTH_TOKEN'
}
r = requests. post( url, data= payload)
print ( r. json( ) )
1 2 3 4 5 6 7 8 9 10 11
{
"result" : "success"
}
1 2 3
Enable Custom User Domains POST /api/v1/settings/canarytokens/user_domains/enable
Enable custom user domains for your Console.
Show details
Required Parameters auth_token string
A valid auth token
Response A JSON structure with result indicator.
Example curl https://EXAMPLE.canary.tools/api/v1/settings/canarytokens/user_domains/enable \
-d auth_token = EXAMPLE_AUTH_TOKEN
1 2
import requests
url = 'https://EXAMPLE.canary.tools/api/v1/settings/canarytokens/user_domains/enable'
payload = {
'auth_token' : 'EXAMPLE_AUTH_TOKEN'
}
r = requests. post( url, data= payload)
print ( r. json( ) )
1 2 3 4 5 6 7 8 9 10 11
{
"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.
Show details
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 curl https://EXAMPLE.canary.tools/api/v1/settings/canarytokens/user_domains/save \
-d auth_token = EXAMPLE_AUTH_TOKEN \
-d user_domains = EXAMPLE_DOMAIN_LIST
1 2 3
import requests
url = 'https://EXAMPLE.canary.tools/api/v1/settings/canarytokens/user_domains/save'
payload = {
'auth_token' : 'EXAMPLE_AUTH_TOKEN' ,
'user_domains' : 'EXAMPLE_DOMAINS_LIST'
}
r = requests. post( url, data= payload)
print ( r. json( ) )
1 2 3 4 5 6 7 8 9 10 11 12
{
"result" : "success"
}
1 2 3
List Custom User Domains GET /api/v1/settings/canarytokens/user_domains/list
List the custom Canarytokens domains for your Console.
Show details
Required Parameters auth_token string
A valid auth token
Response A JSON structure with a list of user domains.
Example curl https://EXAMPLE.canary.tools/api/v1/settings/canarytokens/user_domains/list \
-d auth_token = EXAMPLE_AUTH_TOKEN
1 2
import requests
url = 'https://EXAMPLE.canary.tools/api/v1/settings/canarytokens/user_domains/list'
payload = {
'auth_token' : 'EXAMPLE_AUTH_TOKEN'
}
r = requests. post( url, data= payload)
print ( r. json( ) )
1 2 3 4 5 6 7 8 9 10 11
{
"result" : "success" ,
"user_domains" : [
"your-user-domain.com"
]
}
1 2 3 4 5 6
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.
Show details
Required Parameters auth_token string
A valid auth token
Response A JSON structure with result indicator.
Example curl https://EXAMPLE.canary.tools/api/v1/settings/canarytokens/webroot/disable \
-d auth_token = EXAMPLE_AUTH_TOKEN
1 2
import requests
url = 'https://EXAMPLE.canary.tools/api/v1/settings/canarytokens/webroot/disable'
payload = {
'auth_token' : 'EXAMPLE_AUTH_TOKEN'
}
r = requests. post( url, data= payload)
print ( r. json( ) )
1 2 3 4 5 6 7 8 9 10 11
{
"result" : "success"
}
1 2 3
Enable Custom Canarytokens Site POST /api/v1/settings/canarytokens/webroot/enable
Enable the custom Canarytokens site for your Console.
Show details
Required Parameters auth_token string
A valid auth token
Response A JSON structure with result indicator.
Example curl https://EXAMPLE.canary.tools/api/v1/settings/canarytokens/webroot/enable \
-d auth_token = EXAMPLE_AUTH_TOKEN
1 2
import requests
url = 'https://EXAMPLE.canary.tools/api/v1/settings/canarytokens/webroot/enable'
payload = {
'auth_token' : 'EXAMPLE_AUTH_TOKEN'
}
r = requests. post( url, data= payload)
print ( r. json( ) )
1 2 3 4 5 6 7 8 9 10 11
{
"result" : "success"
}
1 2 3
Set Custom Canarytokens Site POST /api/v1/settings/canarytokens/webroot/save
Set the custom Canarytokens site for your Console.
Show details
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 curl https://EXAMPLE.canary.tools/api/v1/settings/canarytokens/webroot/save \
-d auth_token = EXAMPLE_AUTH_TOKEN \
-d webroot = '<html><body>example!</body></html>'
1 2 3
import requests
url = 'https://EXAMPLE.canary.tools/api/v1/settings/canarytokens/webroot/save'
payload = {
'auth_token' : 'EXAMPLE_AUTH_TOKEN' ,
'webroot' : '<html><body>example!</body></html>'
}
r = requests. post( url, data= payload)
print ( r. json( ) )
1 2 3 4 5 6 7 8 9 10 11 12
{
"result" : "success"
}
1 2 3
Last Updated: 1/10/2025, 12:29:44 PM
