Authentication

There are three different options when it comes to authenticating your requests. Select the approach that works best for your application and programming language.

These authentication methods only apply to the Wine Search and Social APIs. The Account API requires OAuth2.

Be sure to check out the Tools / Libraries / Sample Code page for libraries and code that will implement authentication for you or give you a head start.

Note: The Partner Link API has it’s own authentication model. Please see the detailed documentation for the Partner Link API for details.

Option 1: HTTP Digest

The HTTP Digest authentication scheme is primarily offered to allow API developers to easily browse and explore the VinTank API in an authenticated manner without having to write a single line of code. Just point your browser at apiv1.cruvee.com and begin searching and accessing links to JSON, POSH, and Atom resources. Since most modern web browsers support HTTP Digest, just paste your VinTank API AppId as the “user name” and your VinTank API Secret as the “password” when prompted by your browser.

Here is an example using HTTP digest with curl to return the JSON representation for the Napa Valley region. Just substitute your AppId for “yourAppId” and your API secret for “yourSecret”.

curl --digest -u yourAppId:yourSecret http://apiv1.cruvee.com/regions/8400075.js

Due to the insecure nature of HTTP Basic auth, your request will fail if you use HTTP Basic. In addition your AppID may be deactivated if we see that you’re using HTTP Basic. Just use digest and no one will get hurt!

Of course, if you would like to implement HTTP Digest in your code that integrates with the VinTank API, that will work just fine. There are libraries for several programming languages that will do the authentication work for you. However, you may find that when it comes to writing authentication code, one of the next two options may be more efficient and more convenient.

IMPORTANT: For most applications we do not recommend using HTTP Digest for authenticating your requests. It works great inside a browser but adds an extra round-trip for every one of your requests from your application code (i.e. the HTTP 401 challenge/response). If you are using an HTTP library that is implementing HTTP Digest for you, it may not be apparent that this extra round-trip is occurring since the library is doing this automatically. If your integration with VinTank is from a mobile application or is transactional in nature, eliminating this extra round-trip per request can improve response time. The next two options may require a little more programming but will be worth it. Also, there may be sample code in your programming language that will give you a head start.

Option 2: HTTP Cruvee

The VinTank API supports its own custom HTTP header-based authentication model. It’s simpler than HTTP Digest to implement in most cases and does not require the challenge/response round-trip. All that is required is an HTTP request header in the following format.

Authorization: Cruvee appId="...", sig="...", timestamp="...", uri="..."

Each component of the “Authorization” header is described below.

  • “Cruvee”: the header value must start with “Cruvee” (followed by a space). This tells the API the authentication scheme you’re using.
  • appId: this is the VinTank API AppId that was provided by VinTank when you registered for the API. See getting started.
  • sig: this is the request signature (described below).
  • timestamp: this is an integer-based timestamp from your server when the header was generated. The timestamp value is the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC. The VinTank server will deny your request if your timestamp is +/- 30 seconds from the current time on the VinTank server. If you use a library function such as (or based upon) C’s time() that returns the current time in seconds since the Epoch, be sure to multiply the value returned by this function by 1000 and ensure you cast/convert the value to an long.
  • uri: this is the request URI (request path minus any query string parameters). Ex. /search/brands or /regions/8400075.js.

IMPORTANT: ensure that your server’s clock is synchronized by running a clock synchronization service such as ntp or Windows Time Service. Otherwise, you risk your requests being rejected for stale timestamp values. Also, don’t forget to the send the timestamp in milliseconds.

Option 3: Query String Parameters

Lastly, you can authenticate your API requests using query string parameters. The query string parameter names are similar to the header names from the HTTP Cruvee authentication model.

IMPORTANT: parameter names are case-sensitive (i.e. use “appId” and NOT “appid”).

  • appId: this is the VinTank API AppId that was provided by VinTank when you registered for the API. See getting started.
  • sig: this is the request signature (described below).
  • timestamp: this is a numerical timestamp from your server when the header was generated. The timestamp value is the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC. The VinTank server will deny your request if your timestamp is +/- 10 seconds from the current time on the VinTank server. If you use a library function such as (or based upon) C’s time() that returns the current time in seconds since the Epoch, be sure to multiply the value returned by this function by 1000 and ensure you cast/convert the value to a long.

IMPORTANT: ensure that your server’s clock is synchronized by running a clock synchronization service such as ntp or Windows Time Service. Otherwise, you risk your requests being rejected for stale timestamp values.

A “uri” parameter is not required for this option.

Calculating Signature (“sig”)

The “sig” parameter mentioned above is calculated using the following procedure.

  1. Build a source string by concatenating the values for the following parameters. The parameters must be added in the order specified below and a ‘\n’ (newline) character must be appended to each value. This source-string is ONLY used to calculate the “sig” parameter and must NOT be part of your request.
    1. appId – your Application ID.
    2. HTTP method name used for request (i.e. “GET” or “POST”).
    3. secret – your API application Secret provided by VinTank when you signed up for VinTank’s API. ONLY use for “sig” calculation. NEVER INCLUDE YOUR SECRET ON A URL OR YOUR APP WILL BE DEACTIVATED!
    4. timestamp – same timestamp value from above. MUST BE IN MILLISECONDS.
    5. uri – the request URI (path minus any query string parameters–i.e. path before “?”). Ex. /search/brands or /regions/8400075.js
  2. Lower case the entire source string.
  3. Calculate MD5 hash of source string.
  4. Use MD5 hash as the “sig” parameter in your request.

VinTank will recalculate the signature when your request hits our servers and compare our computed value to the “sig” parameter you provided. If the signatures match, processing of the request will continue. Otherwise the request will be denied and an authentication error will be returned.

Example

Here is an example of how to calculate a signature using the Java programming language for the /search/brands entry point. Examples in other programming languages can be found on the Tools & Libraries page.

String myAppId = "ThisIsMyAppId";
String mySecret = "ThisIsMySecret";
// Already in milliseconds so no need to multiply by 1000.
String timestamp = Long.toString(System.currentTimeMillis());
 
StringBuilder buff = new StringBuilder();
buff.append(myAppId).append("\n");
buff.append("GET").append("\n");
buff.append(mySecret).append("\n");
buff.append(timestamp).append("\n");
buff.append("/search/brands").append("\n");
 
// BE SURE TO LOWER CASE!
String src = buff.toString().toLowerCase();
 
// Use Apache commons codec library to calculate MD5 hash.
// http://commons.apache.org/codec/.
// Libraries/functions should exist for other languages.
String sig = DigestUtils.md5Hex(src);

The “sig” value can then be used in your Authorization header (Option 2) or as a parameter in your request URL (Option 3).

Authorization

For premium APIs that require additional authorization, an additional check is performed after a request is authenticated. This additional check verifies that your API Application (i.e. your AppId) has the necessary permissions enabled based on the request. The API will return an HTTP 403 status code when authorization fails along with a status message indicating that was the case.

Comments are closed.