Iris API Authentication¶

Overview¶

Most requests sent to the DomainTools API require authentication. We support two authentication schemes with different levels of security.

We recommend the following practices for authentication:

Authentication with HTTPS (HTTP over SSL) instead of HTTP.
Using HMAC signed queries or Header Authentication instead of Open Key Authentication.
Using SHA-256 HMAC for the signed queries instead of MD5 or SHA-1.

Protecting API Credentials¶

Your account will be charged for all queries authenticated with your username and key, even if you later determine the requests were fraudulent or its use unauthorized. We recommend the following steps to protect your API credentials:

For support requests, do not send the full API key to DomainTools support.
Use a HMAC-signed approach to requests. This ensures that the user and token are not sent as part of the URL.
When required, reset the API key.
Do not place them into a public repository, such as a git repository.

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

API Key (Header) Authentication¶

Authenticate your requests by including the API key in the header of each HTTP request. The API key serves as a unique identifier and is used to authenticate your requests.

Required API Key Authentication Parameters¶

Required Parameters	Value
`X-Api-Key`	MY_API_KEY

Example Request with API Key Authentication¶

curl -H 'X-Api-Key: MY_API_KEY' 'https://api.domaintools.com/v1/feed/nod/?after=-60

HMAC 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.

MD5, SHA-1, and SHA-256 are supported HMAC hashing algorithms. We recommend SHA256 HMAC, as a successor of SHA1. Although NIST policy on hash functions still allows HMAC SHA-1, see Hash Functions in the NIST CSRC page. Overall, SHA-256 HMAC is also a more secure (ex, against brute force attacks) alternative to MD5 HMAC.

Please check your own compliance obligations, or guidance, as to what cryptographic functions should be used. For example, see the NIST FIPS 140-2 Guidance for more information for organizations that must use FIPS 140-2 compliant algorithms.

HMAC-Signed Authentication URI/Parameters¶

Required Parameters	Value
api_username	Your API username
timestamp	Current timestamp, in ISO 8601 format. Timestamps should contain the timezone offset, like below: 2020-02-01T14:37:59-0800 2020-02-01T22:37:59Z 2020-02-02T10:37:59+1200
signature	HMAC signature of your request. SHA-256 HMAC is recommended. MD5 HMAC and SHA-1 HMAC are supported. Only sign the URL path.

Creating a HMAC-signed authentication request¶

To create the signature, build a string with your API username, the 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 generate the signature. The steps are below.

Add your api_username.

The API username is the account that has been provisioned access to the relevant DomainTools API product (aka API endpoint). If this username does not have access rights, an error message will be returned.
Associate a timestamp.

The timestamp value for the hash and timestamp parameter need to be identical. Make sure your server time is accurate and always use a fresh timestamp.
Add the request URI.

Please see the individual API product User Guides for the endpoint’s URI format.
Add the host.

The host is the API endpoint server. In this case, it is api.domaintools.com.
Use the appropriate HMAC algorithm.

MD5, SHA-1, or SHA-256 for the hashing algorithm are supported. See the HMAC Algorithms section for more information.

The result is a request that expires after a brief period of time and, most importantly, does not contain your authentication key in the clear.

The resulting URLs will generally be similar, regardless of whichever programming language is used.

Security Note¶

Ensure that your current language version supports the required HMAC (and other relevant) extensions and libraries. For example, a failure in HMAC-signed URL will result in a URL with no signature value, such as below:

http://api.domaintools.com/v1/yourdomain.com/whois

Code Samples¶

These code samples are provided for educational purposes.

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 . '&timestamp=' . $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}&timestamp={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}&timestamp=#{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 + "&timestamp="
   + 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 + "&timestamp=" + timestamp);
     Console.Write("Press any key to continue . . . ");
     Console.ReadKey(true);
      }
    }
  }