Overview
Most requests sent to the DomainTools API require authentication. We support two
authentication schemes with different levels of security. Choose the one that best
fits your implementation.
It is vitally important that you protect your API credentials. Your account will be
charged for all queries authenticated with your key even if you later determine the
requests were fraudulent.
Open Key Authentication
This is the easiest authentication scheme to implement, but also the most insecure.
You should take precautions in the design of your application to ensure your key is
not compromised.
https://api.domaintools.com/v1/domaintools.com?api_username=example&api_key=xxxxxx
Required Parameters | Value |
---|---|
api_username | Your API username |
api_key | Your API key |
Signed Authentication
HMAC, or hashed message authentication code, is our preferred authentication
scheme. It follows the principles outlined in RFC2104 and provides a
straightforward but secure method of protecting your API key. It involves passing
a hash composed of your api username, the current date and time, and the request URI.
This hash is then signed with your authentication key.
The result is a request that expires after a brief period of time
and, most importantly, does not contain your authentication key.
Required Parameters | Value |
---|---|
api_username | Your API username |
timestamp | Current timestamp, in ISO 8601 format 2011-02-01T14:37:59-0800 2011-02-01T22:37:59Z 2011-02-02T10:37:59+1200 |
signature | HMAC signature of your request, using the MD5, SHA1, or SHA256 hashing algorithm |
To create the signature, build a string with your api username, a timestamp in
ISO 8601 format, and the URI you are requesting. That string is then signed with
your api key using an HMAC function to give the signature.
Follow these guidelines when building your signature:
- 1) The URI is the part of the URL after api.domaintools.com of your request e.g. /v1/yourdomain.com/whois
- 2) Timestamps should be in ISO 8601 format and contain the timezone offset
- 3) The timestamp value for the hash and timestamp parameter passed to the API need to be identical
- 4) Make sure your server time is accurate and that you always use a fresh timestamp
- 5) Use only MD5, SHA1, or SHA256 for the hashing algorithm
You’ll likely find built-in support for HMAC authentication in your preferred
programming language. We support several hashing algorithms and we closely
follow the HMAC standard to ensure the widest support possible.
NOTE: The following code samples are provided for educational purposes only.
PHP
<?php class DTSigner { private $api_username; private $api_key; public function __construct($api_username, $api_key) { $this->api_username = $api_username; $this->api_key = $api_key; } public function timestamp() { return gmdate("Y-m-dTH:i:sZ"); } public function sign($timestamp, $uri) { return hash_hmac('md5', $this->api_username . $timestamp . $uri, $this->api_key); } } //example of using DTSigner $api_username = 'your_username'; $api_key = 'xxxxx-xxxxx-xxxxx-xxxxx-xxxxx'; $uri = '/v1/yourdomain.com/whois'; $host = 'api.domaintools.com'; $signer = new DTSigner($api_username, $api_key); $timestamp = $signer->timestamp(); $signature = $signer->sign($timestamp, $uri); echo 'https://' . $host . $uri . '?api_username=' . $api_username . '&signature=' . $signature . '×tamp=' . $timestamp; ?>
Python
#!/usr/bin/env python
import hmac
import hashlib
from datetime import datetime, timezone
class DTSigner(object):
def __init__(self, api_username, api_key):
self.api_username = api_username
self.api_key = api_key
def timestamp(self):
return datetime.now(tz=timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
def sign(self, timestamp, uri):
params = "".join([self.api_username, timestamp, uri])
return hmac.new(
self.api_key.encode("utf-8"), params.encode("utf-8"), digestmod=hashlib.sha1
).hexdigest()
if __name__ == "__main__":
api_username = "your_username"
api_key = "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
uri = "/v1/yourdomain.com/whois"
host = "api.domaintools.com"
signer = DTSigner(api_username, api_key)
timestamp = signer.timestamp()
signature = signer.sign(timestamp, uri)
print(
"https://{0}{1}?api_username={2}&signature={3}×tamp={4}".format(
host, uri, api_username, signature, timestamp
)
)
This authentication can also be handled for you by using our official Python API.
Ruby
require 'openssl' class DomainToolsSigner def self.get(username, key, uri) timestamp = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ") data = username+timestamp+uri digester = OpenSSL::Digest::Digest.new("md5") # can be sha1 | sha256 signature = OpenSSL::HMAC.hexdigest(digester, key, data) "api_username=#{username}&signature=#{signature}×tamp=#{timestamp}" end end api_username = 'your_username'; api_key = 'xxxxx-xxxxx-xxxxx-xxxxx-xxxxx'; uri = '/v1/yourdomain.com/whois'; host = 'api.domaintools.com'; authentication = DomainToolsSigner.get(api_username,api_key, uri) puts "https://#{host}#{uri}?#{authentication}"
Java
import javax.crypto.Mac; import java.security.SignatureException; import javax.crypto.spec.SecretKeySpec; import java.text.SimpleDateFormat; import java.util.Date; public class DTSigner { private static final String HMAC_SHA1_ALGORITHM = "HmacSHA1"; private String api_username; private String api_key; private SimpleDateFormat timeFormatter; public DTSigner(String api_username, String api_key) { this.api_username = api_username; this.api_key = api_key; this.timeFormatter = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ssZ"); } public String timestamp() { Date now = new Date(); return this.timeFormatter.format(now); } public String getHexString(byte[] b) { String result = ""; for (int i=0; i < b.length; i++) { result += Integer.toString( ( b[i] & 0xff ) + 0x100, 16).substring(1); } return result; } public String sign(String timestamp, String uri) throws java.security.SignatureException { String Result; try { String data = new String(this.api_username + timestamp + uri); SecretKeySpec signingKey = new SecretKeySpec(this.api_key.getBytes(), HMAC_SHA1_ALGORITHM); Mac mac = Mac.getInstance(HMAC_SHA1_ALGORITHM); mac.init(signingKey); byte[] rawSignature = mac.doFinal(data.getBytes()); Result = this.getHexString(rawSignature); } catch(Exception e) { throw new java.security.SignatureException("Failed to generate HMAC : " + e.getMessage()); } return Result; } public static void main(String args[]) { String api_username = "your_username"; String api_key = "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"; String uri = "/v1/yourdomain.com/whois"; String host = "api.domaintools.com"; try { DTSigner signer = new DTSigner(api_username, api_key); String timestamp = signer.timestamp(); String signature = signer.sign(timestamp, uri); System.out.println("https://" + host + uri + "?api_username=" + api_username + "&signature=" + signature + "×tamp=" + timestamp); } catch(Exception e) { System.out.println("Error trying to sign query"); } } }
C#
using System; using System.IO; using System.Text; using System.Security.Cryptography; namespace DTSigner { class Program { public static String timestamp() { return DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ssZ"); } public static String sign(String api_username, String key, String timestamp, String uri) { ASCIIEncoding encoder = new ASCIIEncoding(); byte[] data = encoder.GetBytes(api_username + timestamp + uri); HMACSHA1 hmac = new HMACSHA1(encoder.GetBytes(key)); CryptoStream cs = new CryptoStream(Stream.Null, hmac, CryptoStreamMode.Write); cs.Write(data, 0, data.Length); cs.Close(); String hex = BitConverter.ToString(hmac.Hash); return hex.Replace("-","").ToLower(); } public static void Main(string[] args) { String api_username = "your_username"; String key = "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"; String uri = "/v1/yourdomain.com/whois"; String host = "api.domaintools.com"; String timestamp = Program.timestamp(); String signature = Program.sign(api_username, key, timestamp, uri); Console.WriteLine("https://" + host + uri + "?api_username=" + api_username + "&signature=" + signature + "×tamp=" + timestamp); Console.Write("Press any key to continue . . . "); Console.ReadKey(true); } } }
- Account Information
- Brand Monitor
- Domain Profile
- Domain Reputation
- Domain Risk Score
- Domain Search
- Hosting History
- IP Monitor
- IP Registrant Monitor
- Iris Detect
- Iris Enrich
- Iris Investigate
- Iris Pivot
- Name Server Monitor
- Parsed Whois
- PhishEye
- Registrant Monitor
- Reverse IP
- Reverse IP Whois
- Reverse Name Server
- Reverse Whois
- Whois History
- Whois Lookup