Authenticating to the throne API

To properly utilize our API you'll need to register for an account and authenticate to our API prior to sending requests to endpoints. Our API utilizes Bearer token authentication in the request headers, without a valid token you will receive an invalid authentication response.

Getting started is easy, visit our registration page and click Sign Up at the bottom to register for an account. Once you're authenticated you can use your credentials to do a POST request to https://api.throne.dev/auth/login with your credentials in the request body in the form of X-WWW-FORM-URLENCODED.

Python - Requests Example

import requests

url = "https://api.throne.dev/auth/login"

payload='username=testuser%40throne.dev&password=Sup3rS3cr3tP@55w0rd!'
headers = {
  'Content-Type': 'application/x-www-form-urlencoded'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

You'll receive a JSON response which contains your Bearer token on an access_token variable.

Token Response

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Inp1Z3RDRWtPM2hvNVIwM3YxbHJZeSJ9.eyJpc3MiOiJodHRwczovL3sdfwer23r4LnVzLmF1dGgwLmNvbS8iLCJzdWIiOiJDSFSD3243rfsadsfsdzRiYTAwNzFmMDExN2EiLCJhdWQiOiJodHRwczovL2FwaS50aHJvbmUuZGV2IiwiaWF0IjoxNjMwNzI2NzY5LCJleHAiOjE2MzA4MTMxNjksImF6cCI6IjdWYUNZdjdOS3piQWw4TkFrRDRFSktITDdHWnl6SVFhIiSDFSEDF3424323fsdfsdfqwewe3243IiLCJndHkiOiJwYXNzd29yZCIsInBlcm1pc3Npb25zIjpbInBlcm06YWRtaW5pc3RyYXRvciJdfQ.",
    "scope": "",
    "expires_in": 86400,
    "token_type": "Bearer"
}

You can then take that token and use it within requests to our API endpoints. This token will need to get sent within the request headers.

Request Example w/ Bearer

import requests

url = "https://api.throne.dev/whois/domain?query=amazon.com"

payload={}
headers = {
  'Authorization': 'Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Inp1Z3RDRWtPM2hvNVIwM3YxbHJZeSJ9.eyJpc3MiOiJodHRwczovL3sdfwer23r4LnVzLmF1dGgwLmNvbS8iLCJzdWIiOiJDSFSD3243rfsadsfsdzRiYTAwNzFmMDExN2EiLCJhdWQiOiJodHRwczovL2FwaS50aHJvbmUuZGV2IiwiaWF0IjoxNjMwNzI2NzY5LCJleHAiOjE2MzA4MTMxNjksImF6cCI6IjdWYUNZdjdOS3piQWw4TkFrRDRFSktITDdHWnl6SVFhIiSDFSEDF3424323fsdfsdfqwewe3243IiLCJndHkiOiJwYXNzd29yZCIsInBlcm1pc3Npb25zIjpbInBlcm06YWRtaW5pc3RyYXRvciJdfQ.'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Once you send that request you should receive a valid response, using our example above this is what the response should look like.

Request Response

{
    "handle": "281209_DOMAIN_COM-VRSN",
    "domain": "amazon.com",
    "registrar_rdap": "https://rdap.markmonitor.com/rdap/domain/amazon.com",
    "status": [
        "client update prohibited",
        "client transfer prohibited",
        "client delete prohibited",
        "server update prohibited",
        "server transfer prohibited",
        "server delete prohibited"
    ],
    "registrar": {
        "name": "MarkMonitor Inc.",
        "role": "registrar",
        "iana_id": "292",
        "contact_info": {
            "abuse": [
                {
                    "phone": "+1.2083895740",
                    "email": "[email protected]"
                }
            ]
        }
    },
    "whois": {
        "domain": "amazon.com",
        "nameservers": [
            "ns1.p31.dynect.net",
            "ns2.p31.dynect.net",
            "ns3.p31.dynect.net",
            "ns4.p31.dynect.net",
            "pdns1.ultradns.net",
            "pdns6.ultradns.co.uk"
        ],
        "dnssec": [
            {
                "signed": false,
                "dsData": []
            }
        ],
        "contact_info": {
            "administrative": [
                {
                    "name": "Hostmaster, Amazon Legal Dept.",
                    "org": "Amazon Technologies, Inc.",
                    "address": "P.O. Box 8102, Reno, NV, 89507, US",
                    "phone": "+1.2062667010",
                    "email": "[email protected]"
                }
            ],
            "registrant": [
                {
                    "name": "Hostmaster, Amazon Legal Dept.",
                    "org": "Amazon Technologies, Inc.",
                    "address": "P.O. Box 8102, Reno, NV, 89507, US",
                    "phone": "+1.2062667010",
                    "email": "[email protected]"
                }
            ],
            "technical": [
                {
                    "name": "Hostmaster, Amazon Legal Dept.",
                    "org": "Amazon Technologies, Inc.",
                    "address": "P.O. Box 8102, Reno, NV, 89507, US",
                    "phone": "+1.2062667010",
                    "email": "[email protected]"
                }
            ],
            "registrar": [
                {
                    "name": null,
                    "org": "MarkMonitor Inc.",
                    "address": "3540 E Longwing Ln, Meridian, ID, 83646, US",
                    "phone": null,
                    "email": null
                }
            ]
        },
        "registration_info": {
            "expiration": "2024-10-30T07:00:00.000+0000",
            "registration": "1994-11-01T05:00:00.000+0000",
            "last update": "2019-08-26T19:19:56.000+0000",
            "last update of RDAP database": "2021-09-04T04:03:07.000+0000"
        }
    }
}