Application IDs and Shared Secret Keys

What is an Application ID?


Application IDs identify you to Healthx as a unique application developer. Each application ID can register up to 10 seperate applications to use OpenX APIs (OxAPIs). Each application ID is limited to 1000 calls every 24 hours. If you need more than 10 applications, or think you'll exceed the 1000 calls every 24 hours, it's no problem, just shoot us an e-mail.

What's a Shared Secret Key?


Your shared secret key is the tool we use to authenticate your application's calls. The secret key means that even if someone finds out your unique application ID, they cannot make requests on your behalf. You should not share your secret key with anyone.

How do secret keys work?


You use your shared secret key to encode (hash) a signature string (we sometimes call this an authorization or auth string). You'll send a request to a URL which will include your query string as well as your encoded signature. We'll decode your signature, verifying the source of the request. We'll then process your query.




The signature string is a special string, encoded as an SHA hash. It includes the concatenated and hashed values of your application ID, a timestamp (in UTC), and your signature string version. We decode your hash using your application ID and a timestamp, which you'll send us on your query string, as well as your shared secret key, which we'll look up via your application ID.




Your shared secret key allows us to confirm that the request we've received came from you, and the timestamp confirms its recency.

How do I build my signature?


You can create your signature in two steps. First, hash the key values from your query string (App ID, DateTime, Signature Version - in that order) using SHA1. Then, because the hash function returns non-URL compliant characters, you must encode your hash into a 64-bit string.


Sample Create Signature Code

            string appid = "myappid-guid";
            string timestamp = DateTime.Now.ToString("o");// ex. 2006-04-17T14:22:48.2698750-07:00
            string sigVersion = "V1";
            string sig = GenerateSignature(appid, timestamp, sigVersion);      

    private static string GenerateSignature(string appid, string timestamp, string signatureVersion)
        {
            string newSig = "";
            string MY_SHARED_SECRET = "thisismysecret";

            HMACSHA1 hmac = new HMACSHA1(Encoding.ASCII.GetBytes(MY_SHARED_SECRET));
            byte[] hashValue = hmac.ComputeHash(Encoding.ASCII.GetBytes(appid + timestamp + signatureVersion));
           
            newSig = Convert.ToBase64String(hashValue);

            return newSig;
        }

Notice that the sample code calls DateTime.Now.ToString("o"). We could also call the system helper service OpenX Timestamp for this information.

Got it. I want in. How do I get started?


Relax. Get your Application ID here.