Signature Generation
Objective
Explain the Signature attribute used in all SyncTV APIs and demonstrate how they are generated.
Requirements
  • A means to generate MD5 hashes from string inputs
APIs Covered
For this tutorial we will be using the below query string and access secret.
    Query String
    https://service-name.synctv.com/api/v2/accounts.xml?access_id=13406&account[password]=alpha21&account[email]=testperson@synctv.com&account[password_confirmation]=alpha21&signature=
    Access Secret
    eEcBb8sttnyBXF2veW8WzohSGvBv7BJ13EqqrcfnhBkr
Step 1
Breaking Apart the Parameter Value Pairs
With a constructed API query we now need to generate the signature. The first step is breaking apart the parameter=value pairs. The pairs are below, notice the ampersands from the full query are not included.
  • access_id=13406
  • account[password]=alpha21
  • account[email]=testperson@synctv.com
  • account[password_confirmation]=alpha21
We break these pairs apart into their parameters and their values, as given below. Notice that the equal signs have been removed.
  • access_id 13406
  • account[password] alpha21
  • account[email] testperson@synctv.com
  • account[password_confirmation] alpha21
Step 2
URL Escaping the Pairs
We then URL escape the parameters and values, the results are shown below.
  • access_id 13406
  • account%5Bpassword%5D alpha21
  • account%5Bemail%5D testperson%40synctv.com
  • account%5Bpassword_confirmation%5D alpha21
Notice the change of the @ symbol in the email address. Not all libraries that support URL escaping support it in full. For a full list of reserved characters in URL query escaping please refer to: http://www.december.com/html/spec/esccodes.html
Step 3
Re-concatenating the Pairs
With the parameters and values escaped we now add the equal signs back in and re-concatenate the pairs back together as shown below.
  • access_id=13406
  • account%5Bpassword%5D=alpha21
  • account%5Bemail%5D=testperson%40synctv.com
  • account%5Bpassword_confirmation%5D=alpha21
Notice the equal signs are not escaped. We only escape the parameters and the values, not the characters between them.
Step 4
Alphabetize the Pairs
With the parameters and values re-concatenated we now alphabetize the escaped pairs, this is demonstrated below.
  • access_id=13406
  • account%5Bemail%5D=testperson%40synctv.com
  • account%5Bpassword%5D=alpha21
  • account%5Bpassword_confirmation%5D=alpha21
The pairs must be alphabetized after escaping because not all libraries weigh unescaped characters equally and incorrectly ordered strings will not generate a proper signature.
Step 5
Assembling the String for Hashing
In order to generate the proper hash value we need to re-concatenate the entire string and append the access secret to the end. We reassemble the parameter=value pairs into the complete string we started with, adding ampersands between each pair then append the access secret to the end. This is demonstrated below.
access_id=13406&account%5Bemail%5D=testperson%40synctv.com&account%5Bpassword%5D=alpha21&account%5Bpassword_confirmation%5D=alpha21eEcBb8sttnyBXF2veW8WzohSGvBv7BJ13EqqrcfnhBkr
Notice the ampersands are not escaped and there is no ampersand between the last value and the access secret. Do not place an ampersand here, if you do your hash will not be correct.
Step 6
Generating the Hash
The signature is a standard thirty two character MD5 hash fingerprint. To generate a signature for use with the SyncTV service, hash the assembled string from step four with the MD5 algorithm. The result is below.
7c1700fa9105116efc5501651df9250f
The complete query:
https://service-name.synctv.com/api/v2/accounts.xml?access_id=13406&account[email]=testperson@synctv.com&account[password]=alpha21&account[password_confirmation]=alpha21&signature=7c1700fa9105116efc5501651df9250f