Introduction

Welcome to the API documentation of www.tokendns.co the premium dns service to enpower your online business. We try to offer you a simple and easy API to integrate. No one likes to waste money and time on integrating new services in his platform.

Every section will start with a overview of all options that the endpoint is accepting. Followed with some examples with curl that you can run in your terminal emulator. Lets start with a small example on how to get your current public ip address:

How To Get My IP?

curl https://ip.tokendns.co

Result:

127.0.0.1

In this example we do not use any variables, but they will be crucial when you go through our documentation. How do you recognize them? Easy, they look like this ${variable}. They needs to be replaced with the correct value. In the Query Parameter you can see the default values and some examples.

What To Consider?

Please consider that all parameter are GET parameter and therefore easy to createt a request. In this documentation you will see the examples in following style:

curl --get https://ip.tokendns.co \
  -d json=true

But you can also build the parameter in one long url. This is somethimes the only way in appliances or your home router:

curl https://ip.tokendns.co/?json=true

Both options are completely valid and can be used as you wish.

Codes

Every request will return a json formatted return with a code and message.

Success And Error Codes

Code Description
200 Success
400 Bad Request (You probably missing a parameter)
401 Unauthorized

Now you can have fun and if you find anything strange or have a question, don't hesitate to contact us: hello@tokendns.co.

Client Libraries

We want you to get start coding and not reading. We are providing several client libraries that you can use in your favorite language.
Head over to github.com and get started.

Domains

Query Parameter

Parameter Default Example Description
apikey Your secret apikey
action add Selected option to execute
domain blabladns.xyz Domain Name
method email http Verification method
billing monthly yearly Payment interval
voucher Got a voucher? You are lucky!
email webmaster@blabladns.xyz Used email address when verification method is email
period 1 3 The time you want to buy a domain (in years)
shield yes no Security shield that your data is not shown in the whois database.
service gmail Autoconfiguration for new records: gmail, github, gitlab, tumblr, cloudoffice (comma seperated if you want to use multiple).
nameserver ns1.tokendns.co,ns2.tokendns.co,ns3.tokendns.co Nameserver that will be used. At least two needs to be used.
autorenew yes no Auto renew for domains



Add Domain

When you did the right choice to use TokenDNS you need to register your domain with us, but we need to make sure that you own the domain. Otherwise everyone could register any domain with us and make foolish stuff. We offer three options to verify the ownership of the domain:

  • Email
  • DNS
  • HTTP

Each of the options has its advantages, but if you don't know what the other means you should choose Email. Recipients are limited to webmaster and admin.




Register Domain With Email Verification

curl --get "https://api.tokendns.co/v1/domains" \
  -d apikey=${apikey} \
  -d action=add \
  -d domain=${domain} \
  -d method=email \
  -d email=webamster@${domain} \
  -d billing=yearly

Response:

{
    "status": "200",
    "message": "Domain added for verification. Please check your emails.",
    "method": "email"
}



Register Domain With DNS Verification

curl --get "https://api.tokendns.co/v1/domains" \
  -d apikey=${apikey} \
  -d action=add \
  -d domain=${domain} \
  -d method=dns \
  -d billing=yearly

Response:

{
   "method" : "dns",
   "txt_record" : "tokendns-site-verification=c40242a3fc40f73d",
   "status" : "200",
   "message" : "Domain added for verification. Please create the TXT record."
}

In the response you see the content of the TXT record that you need to create with your current dns provider.




Register Domain With HTTP Verification

curl --get "https://api.tokendns.co/v1/domains" \
  -d apikey=${apikey} \
  -d action=add \
  -d domain=${domain} \
  -d method=http \
  -d billing=yearly

Response:

{
   "method" : "http",
   "message" : "Domain added for verification. Please create the file.",
   "content" : "264a99aa767f7ae2bfdc1e5dc2c30509b2297e9d",
   "status" : "200",
   "url" : "blabladns.xyz/tokendns-site-verification-35741b788fc63a67.html"
}

The url need to contain the specific content from the response. You need to create his file on your server or hosting provider.




Register Domain

We offer free domains for .tk .ga .gq .cf and .ml at the moment. You can register these at no costs. Please note that you need to serve a website on the registered domain. Not used websites are subject to get removed.

curl --get "https://api.tokendns.co/v1/register" \
  -d apikey=${apikey} \
  -d action=add \
  -d domain=${domain} \
  -d period=1 \
  -d shield=yes \
  -d service=gmail \
  -d nameserver=ns1.tokendns.co,ns2.tokendns.co,ns3.tokendns.co \
  -d autorenew=yes

Response:

{
    "status": "200",
    "message": "Domain blabladns.xyz registered"
}



Check Domain

Check if a domain is available to register

curl --get "https://api.tokendns.co/v1/register" \
  -d apikey=${apikey} \
  -d action=check \ 
  -d domain=${domain}

Response:

{
    "status": "200",
    "message": "Domain is available"
}



List Domains

Need an overview of your domains? Dont look further.

curl --get "https://api.tokendns.co/v1/domains" \
  -d apikey=${apikey} \
  -d action=list

Response:

{
   "domains" : [
      [
         {
            "domain" : "tokendns.co",
            "billing" : "monthly",
            "paid_until" : "2017-08-22 20:17:55",
            "registered_at" : "2016-08-22 20:17:55"
         },
         {
            "domain" : "blabladns.xyz",
            "billing" : "yearly",
            "paid_until" : "2017-08-22 22:17:55",
            "registered_at" : "2017-08-21 22:17:53"
         }
      ]
   ],
   "status" : "200"
}



Delete Domain

Delete your domain.

curl --get "https://api.tokendns.co/v1/domains" \
  -d apikey=${apikey} \
  -d action=delete \ 
  -d domain=${domain}

Response:

{
    "status": "200",
    "message": "Domain deleted",
    "domain": "blabladns.xyz"
}





Records

Query Parameter

Parameter Default Example Description
apikey Your secret apikey
name www Name of your subdomain/record
domain blabladns.xyz Domain Name
content 127.0.0.1 The content of your record (if not supplied it usese the ip you connect from)
ttl 300 Time to live of your dns record
type A record type can be: A, AAAA, MX, SOA, TXT, SPF, NS, CNAME, PTR, SRV
priority 0 Priority of you dns record
service gmail Autoconfiguration for new records: gmail, github, gitlab, tumblr, cloudoffice (comma seperated if you want to use multiple).
tag website Note for your dns record to remember what it is for



Create Record

What would a domain do without any record? Nothing! Lets start and create some. In our example we set the content automatically to our public ip. We did not used the domain parameter, because its default value is blabladns.xyz.

curl --get "https://api.tokendns.co/v1/reserve" \
  -d apikey=${apikey} \
  -d name=${name} \
  -d domain=${domain} \
  -d type=A \
  -d content=$(curl -s -4 https://ip.tokendns.co)

Response:

{
    "status": "200",
    "message": "Fantastic! www.blabladns.xyz is reserved for you. Please update your A and AAAA records now"
}



Update Record

curl --get "https://api.tokendns.co/v1/update" \
  -d apikey=${apikey} \
  -d name=${name} \
  -d domain=${domain} \
  -d type=A \
  -d content=$(curl -s -4 https://ip.tokendns.co)

Response:

{
    "status": "200",
    "message": "Updated"
}



Delete Record

curl --get "https://api.tokendns.co/v1/delete" \
  -d apikey=${apikey} \
  -d name=${name} \
  -d domain=${domain} \
  -d type=A \
  -d content=${content}

Response:

{
    "status": "200",
    "message": "Deleted A for www.blabladns.xyz"
}



Status of Record

curl --get "https://api.tokendns.co/v1/status" \
  -d apikey=${apikey} \
  -d domain=${domain} \
  -d name=${name}

Response:

{
    "status": "200",
    "domain": "www.blabladns.xyz",
    "records": [
    [{
      "name": "www.blabladns.xyz",
      "type": "A",
      "content": "178.62.218.113",
      "ttl": "300",
      "change_date": "1450795478"
    }, {
      "name": "www.blabladns.xyz",
      "type": "AAAA",
      "content": "::1\/128",
      "ttl": "300",
      "change_date": "1450795478"
    }]
  ]
}





Tags

Query Parameter

Parameter Default Example Description
apikey Your secret apikey
name www Name of the tag
domain blabladns.xyz Domain Name



List Tags

Tags are an amazing feature to keep track of your records. Never wonder about some dns records and think about in which project or product you used them.

curl --get "https://api.tokendns.co/v1/tags" \
  -d apikey=${apikey} \
  -d name=${name} \
  -d domain=${domain}

Response:

{
    "status": "200",
    "domain": "blabladns.xyz",
    "tag": "website",
    "records": [
     [
        {
          "name": "www.blabladns.xyz",
          "type": "A",
          "content": "172.168.0.1"
       },
        {
          "name": "www.blabladns.xyz",
          "type": "AAAA",
         "content": ""
        },
        {
          "name": "my.blabladns.xyz",
          "type": "A",
         "content": "172.168.0.1"
        }
      ]
    ]
  }





FailoverDNS

Query Parameter

Parameter Default Example Description
apikey Your secret apikey
domain blabladns.xyz Domain Name
action add Selected option to execute
status enable status Enable or disabled status of your check
url Full URL to your healtcheck
record_type A Which record type to be changed
record_name www Which record name to be changed
record_content New content for the record if the check fails
record_original Original content of the record (does nothing)
response_type code content Expected response of the check (more details when creating it)
response_content 200 Expected content of check
retry 4 How often a check needs to fail before we change the content
id 12 Identification number of the check (can be received through listing checks)



Create FailoverDNS

What is a FailoverDNS and why do should I need it? First of all it is not useful for every system, but can help you in many cases. Need high availability and got multiple servers for your application? Then Failover DNS is the fastest way to achieve this. We update your DNS automatically when your primary service is not working anymore.
We offer two types of checks:

  • Code
  • Content

With code we check the return value of the http check and content we are looking for a regular expression in the content of the website. Please note that we do not follow any redirects!

curl --get "https://api.tokendns.co/v1/failoverdns" \
  -d apikey=${apikey} \
  -d domain=${name} \
  -d action=add \
  -d status=enable \
  -d url=${url} \
  -d record_type=${type} \
  -d record_name=${name} \
  -d record_content=${content} \
  -d record_original=${content} \
  -d response_type=${code|content} \
  -d response_content=${result} \
  -d retry=7

Response:

{
    "status": "200",
    "message": "Add failover dns service for www.blabladns.xyz"
}



List FailoverDNS

curl --get "https://api.tokendns.co/v1/failoverdns" \
  -d apikey=${apikey} \
  -d domain=${name} \
  -d name=${name} \
  -d action=list

Response:

{
    "status": "200",
    "domain": "blabladns.xyz",
    "failoverdns": [
      [
        {
          "id": "8",
          "status": "1",
          "url": "http://www.blabladns.xyz",
          "record_name": "www",
          "record_type": "A",
          "record_content": "8.8.8.8",
          "record_original": "127.0.0.2",
          "response_type": "code",
          "response_content": "200",
          "retry": "6"
       }
     ]
   ]
}



Status FailoverDNS

Disable or Enable your check (e.g. when you are having a maintenance or deploying a new release on your application)

curl --get "https://api.tokendns.co/v1/failoverdns" \
  -d apikey=${apikey} \
  -d domain=${name} \
  -d id=${id} \
  -d status=enable \
  -d action=status

Response:

{
    "status": "200",
    "message": "Failover DNS enable"
}



Delete FailoverDNS

curl --get "https://api.tokendns.co/v1/failoverdns" \
  -d apikey=${apikey} \
  -d domain=${name} \
  -d id=${id} \
  -d action=delete

Response:

{
    "status": "200",
    "message": "Failover DNS deleted"
}





Notifications

Query Parameter

Parameter Default Example Description
apikey Your secret apikey
action add
provider email Provider name you want to use
domain blabladns.xyz Set the domain you want to use
id 12 Identification number of the notification (used when deleting)
status enable disable Enable or Disable a notification
recipient webmaster@blabladns.xyz Email recipient
user User configuration (provider)
token Token configuration (provider)
webhook http://www.blabladns.xyz/webhook.php Callback URL for the webhook
description Description of your notification
priority 0 1 Priority configuration (provider)



Email Notification

curl --get "https://api.tokendns.co/v1/notifications" \
  -d apikey=${apikey} \
  -d action=add \
  -d domain=${domain} \
  -d provider=email \
  -d recipient=${address}

Response:

{
    "status": "200",
    "message": "New Email notification configured"
}



Slack Notification

curl --get "https://api.tokendns.co/v1/notifications" \
  -d apikey=${apikey} \
  -d action=add \
  -d domain=${domain} \
  -d provider=slack \
  -d channel=${slack_channel} \
  -d webhook=${webhook_url}

Response:

{
  "status": "200",
  "message": "New Slack webhook configured"
}

Note: The Slack channel should be without the hashtag (#) or encode it properly.




PushOver Notification

curl --get "https://api.tokendns.co/v1/notifications" \
  -d apikey=${apikey} \
  -d action=add \
  -d domain=${domain} \
  -d provider=pushover \
  -d user=${user_id} \
  -d token=${token_id}

Response:

{
    "status": "200",
    "message": "New PushOver notification configured"
}



Messenger Notification

No API at the moment. Please open Messenger to configure.




PagerDuty Notification

curl --get "https://api.tokendns.co/v1/notifications" \
  -d apikey=${apikey} \
  -d action=add \
  -d domain=${domain} \
  -d provider=pagerduty \
  -d description=${service_description} \
  -d token=${token_id}

Response:

{
    "status": "200",
    "message": "Notification configured"
}



Webhooks Notification

curl --get "https://api.tokendns.co/v1/notifications" \
  -d apikey=${apikey} \
  -d action=add \
  -d domain=${domain} \
  -d provider=webhook \
  -d webhook=${webhook_url}

Response:

{
    "status": "200",
    "message": "New Webhook notification configured"
}



Status of Notification

curl --get "https://api.tokendns.co/v1/notifications" \
  -d apikey=${apikey} \
  -d action=status \
  -d domain=${domain} \
  -d status=enable \
  -d id=${id}

Response:

{
   "message" : "Notification enable",
   "status" : "200"
}



List of Notification

curl --get "https://api.tokendns.co/v1/notifications" \
  -d apikey=${apikey} \
  -d action=list \
  -d domain=${domain} \
  -d provider=${provider}

Response:

{
            "recipient" : "webmaster@blabladns.xyz",
            "status" : "1",
            "id" : "4"
}





Settings

Query Parameter

Parameter Default Example Description
apikey Your secret apikey
action Selected option to execute
value Value for the action
billing_name Your full name
billing_address1 Address
billing_address2 Optional address
billing_city City
billing_zip Postalcode
billing_country Country



Change Email

curl --get "https://api.tokendns.co/v1/settings" \
  -d apikey=${apikey} \
  -d action=email \
  -d value=${new_email}

Response:

{
  "status" : "200",
  "message" : "Email updated. Please check your inbox and verify your email."
}



Change Username

curl --get "https://api.tokendns.co/v1/settings" \
  -d apikey=${apikey} \
  -d action=username \
  -d value=${new_username}

Response:

{
  "status" : "200",
  "message" : "Username updated"
}



Reset Apikey

curl --get "https://api.tokendns.co/v1/settings" \
  -d apikey=${apikey} \
  -d action=apikey

Response:

{
  "status" : "200",
  "message" : "Apikey changed"
}



Update Address

curl --get "https://api.tokendns.co/v1/settings" \
  -d apikey=${apikey} \
  -d action=address \
  -d billing_name=${your_name} \
  -d billing_address1=${addres} \
  -d billing_address2=${optionaladdress} \
  -d billing_city=${city} \
  -d billing_zip=${postalcode} \
  -d billing_country=${country} 

Response:

{
  "status" : "200",
  "message" : "Address updated"
}





Export

Query Parameter

Parameter Default Example Description
apikey Your secret apikey
action records Selected option to execute
domain blabladns.xyz Set the domain you want to use
tld tk If no tld is defined, all will be shown



Export Records

curl --get "https://api.tokendns.co/v1/export" \
  -d apikey=${apikey} \
  -d action=records \
  -d domain=${domain}

Response:

{
  "status": "200",
  "domain": "blabladns.xyz",
  "records": [
    [
      {
        "name": "blabladns.xyz",
        "type": "TXT",
        "content": "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCFPb9PnIJB8z2Ev+C+jmNPVVLxGMeqDNKOoa9/9R/C6rgRkLcxFHAB4ibbr7h7ybngirME0jsn4ZgBsweaRSfqdj5Arka1luqEAKxaBW6K6pi9HDvRpWQzFdwQriUcWyyIVsCjYEQLZJdZOD8nX9sJk5u+ihlumstZaTIIUFA/jQIDAQAB",
        "ttl": "300",
        "change_date": "1485196067",
        "tag": ""
      },
      {
        "name": "asd.blabladns.xyz",
        "type": "A",
        "content": "127.0.0.5",
        "ttl": "300",
        "change_date": "1471774941",
        "tag": ""
      },
      {
        "name": "asd.blabladns.xyz",
        "type": "A",
        "content": "10.10.10.10",
        "ttl": "300",
        "change_date": "1485419347",
        "tag": ""
      },
      {
        "name": "facebook.blabladns.xyz",
        "type": "A",
        "content": "188.166.134.65",
        "ttl": "300",
        "change_date": "1469030691",
        "tag": ""
      },
      {
        "name": "facebook.blabladns.xyz",
        "type": "MX",
        "content": "127.0.0.1",
        "ttl": "300",
        "change_date": "1469030795",
        "tag": ""
      },
      {
        "name": "insomnia.blabladns.xyz",
        "type": "A",
        "content": "178.62.218.50",
        "ttl": "300",
        "change_date": "1481653536",
        "tag": "website"
      },
      {
        "name": "www.blabladns.xyz",
        "type": "A",
        "content": "8.8.8.8",
        "ttl": "300",
        "change_date": "1469028995",
        "tag": ""
      },
      {
        "name": "www3.blabladns.xyz",
        "type": "A",
        "content": "127.0.0.12",
        "ttl": "300",
        "change_date": "1483823787",
        "tag": "website"
      }
    ]
  ]
}



Export Pricelist

curl --get "https://api.tokendns.co/v1/export" \
  -d apikey=${apikey} \
  -d action=pricelist \
  -d tld=${tld}

Response:

{
  "status": "200",
  "pricelist": [
    [
      {
        "tld": "tk",
        "privacy": "1",
        "1y": "0",
        "2y": "0",
        "3y": "0",
        "4y": "0",
        "5y": "0"
      },
      {
        "tld": "ml",
        "privacy": "1",
        "1y": "0",
        "2y": "0",
        "3y": "0",
        "4y": "0",
        "5y": "0"
      },
      {
        "tld": "ga",
        "privacy": "1",
        "1y": "0",
        "2y": "0",
        "3y": "0",
        "4y": "0",
        "5y": "0"
      },
      {
        "tld": "cf",
        "privacy": "1",
        "1y": "0",
        "2y": "0",
        "3y": "0",
        "4y": "0",
        "5y": "0"
      },
      {
        "tld": "gq",
        "privacy": "1",
        "1y": "0",
        "2y": "0",
        "3y": "0",
        "4y": "0",
        "5y": "0"
      }
    ]
  ]
}