API Authentication

App IDs and Shared Secrets

Each application has an app_id and an app_secret. The app_id is public and is simply used to identify the application. The app_secret is something that is known only by Hunch and the application and can be used to authenticate the application to Hunch and vice-versa. The authentication using this app_secret is via an auth_sig.

The auth_sig is computed using the following process:

  • Encode the URL arguments and their values in utf-8.
  • Sort the URL arguments into ascending order using the ASCII sort order.
  • URL form encode the arguments using '+' for spaces, according to RFC-1738 so that only alphanumerics [0-9a-zA-Z], the special characters "$-_.+!*'()," [not including the quotes], and reserved characters used for their reserved purposes may be used unencoded within a URL.
  • Concatenate the encoded URL arguments with the application secret.
  • Compute the 40 character hex encoded SHA-1 hash of the concatenated string.
  • Pass the hash as a URL argument named auth_sig.

Examples of computing an auth_sig in various languages can be found under code samples, and the API console automatically computes and displays an auth_sig for your app.

OAuth

Users OAuth into Hunch in order to give an application access to their Hunch taste profile data. The end result of the OAuth process is an auth_token that allows an app to make future requests on behalf of that user. The user may at any time revoke your application's access to their taste profile.

To perform the OAuth process:

  • Send the user to http://hunch.com/authorize/v1/ so they can give your application access to their Hunch taste profile. Your app will have to include its app_id and an optional next parameter which will be returned to your application after the authorization process. 
    http://hunch.com/authorize/v1/?app_id=12345&next=/get-recs
  • Hunch will allow the user to log into an existing Hunch account or create a new account via Facebook or Twitter.
  • When the user has accepted or rejected the application, they will be redirected to the URL registered with your application, or to the next URL if none is registered with your application. The redirected URL will include as URL arguments the same next parameter you provided earlier, an auth_token_key, and an auth_sig which you can optionally use to verify that the request is actually from Hunch. 
    http://your-domain.com/authorized/?auth_token_key=7a1b2c3&auth_sig=941bc415af782a8d93a83c874922ae1b30e92a70&next=/get-recs
  • Once the user has been redirected back to your application's page, call get-auth-token with the auth_token_key received in the previous step. This call will return a user_id and an auth_token.
  • Your application can check the status of an auth_token at any time by calling the check_auth_token method in the API.

IFrame Applications

Building an application on Hunch gives you the ability to integrate your website into the core Hunch experience. Applications that run within hunch.com all use the same technologies as websites which integrate Hunch recommendations.

When you build an application on Hunch, your application's views come from an iframe hosted at http://hunch.com/your-app-name/ that points to your application.

Both logged in and non-logged in users can view your application on Hunch. In the former case, the variables hn_user_id, hn_timestamp, and hn_auth_sig will be passed into the iframe as URL arguments. In the latter case, only hn_timestamp and hn_auth_sig will be provided.