General

Version 4

Version 3

Version 2

Authentication

All requests to the IIHS API must be authenticated. When your account is approved, you're assigned a unique API key which is central to verifying your application's identity. Your key can be found on the Authentication tab of your account settings page. There are two ways your API key can be used to authenticate your API calls:

Method 1: Signature-based authentication (more secure)

This authentication method uses your API key to generate a cryptographically signed token that's included in your API request. Since your API key itself is never sent across the internet, this method is better for applications where API calls are issued from devices outside your control.

To use this method:

1. Create an array of 8 random bytes. This nonce ensures that consecutive API calls produce different tokens, even if the calls are otherwise identical.

   var nonce = new byte[8];
   new System.Security.Cryptography.RNGCryptoServiceProvider().GetBytes(nonce);

2. Select an expiration date for the token, and express it as the bytes of a Unix timestamp (a 32-bit signed integer representing the number of seconds since January 1, 1970).

   static readonly DateTime Epoch = new DateTime(1970, 1, 1, 0, 0, 0, DateTimeKind.Utc);
   var expiryTime = DateTime.UtcNow.AddMinutes(30);
   var seconds = (long)((expiryTime - Epoch).TotalSeconds);
   var expiryBytes = BitConverter.GetBytes(seconds);

3. Concatenate your account name, API key, and the nonce and expiry byte arrays together. Then calculate the SHA-1 hash of the resulting array.

   var accountNameBytes = System.Text.Encoding.UTF8.GetBytes(accountName);
   var apiKeyBytes = System.Text.Encoding.UTF8.GetBytes(apiKey);
   var bytesToHash = accountNameBytes
       .Concat(apiKeyBytes)
       .Concat(nonce)
       .Concat(expiryBytes)
       .ToArray();
   var hash = new System.Security.Cryptography.SHA1CryptoServiceProvider().ComputeHash(bytesToHash);

4. Concatenate the expiry byte array, the nonce, and the hash together to create the final token. Encode this byte array in Base64 for transport over HTTP.

   var token = expiryBytes
       .Concat(nonce)
       .Concat(hash).ToArray();
       var tokenString = Convert.ToBase64String(token);

5. Add your account name (the username you use to log into this site) and the signed token to your HTTP request. These can either be added to the URL querystring using the parameter names accountname and auth:

   http://api.iihs.org/v2/ratings/modelyears?accountname=YOUR_ACCOUNT_NAME&auth=SIGNED_TOKEN

   Or they can be supplied as custom HTTP headers under the names IIHS-accountname and IIHS-auth:

   GET /v2/ratings/modelyears HTTP/1.1
   User-Agent: MyAutoSafetyApp/v1
   Pragma: no-cache
   Accept-Language: en-US
   Host: api.iihs.org
   IIHS-accountname: YOUR_ACCOUNT_NAME
   IIHS-auth: SIGNED_TOKEN

Method 2: Include your API key with the call (less secure)

This authentication method requires less code to implement, but since your API key is transferred in plain text over the network, it's not as secure as using signature-based authentication. This method should only be used in situations where the device accessing the IIHS API is one you control, and ideally all requests should be issued over an SSL connection to prevent intermediate network nodes from seeing your API key.

To use this method, add a custom HTTP header called IIHS-apikey to your request, with your plaintext API key as its value:

GET /v2/ratings/modelyears HTTP/1.1
User-Agent: MyAutoSafetyApp/v1
Pragma: no-cache
Accept-Language: en-US
Host: api.iihs.org
IIHS-apikey: YOUR_API_KEY

You may also include your key as a querystring parameter, but this method is not recommended since your key is exposed to intermediate nodes even over an SSL connection:

https://api.iihs.org/v2/ratings/modelyears?apikey=YOUR_API_KEY