DKos API Authentication Scheme

This isn't active here yet, but I've settled on an authentication scheme for the API. It's waiting on me cleaning up the Perl module that will act as a reference client implementation and finishing the method, which will be the first thing you'd actually need authentication for.

It took some thinking to come up with a way to handle authentication via the API, because of certain details of Scoop's native authentication measures. I finally settled on this:

  1. Get a token. There will be a page that will generate and store your token in the database for you. Keep it somewhere safe. If it gets compromised or you lose it, just go generate a new one. It'll replace the old one.
  2. When making a request, you'll need to include three authenication parameters:
    • Your username, as user=UserName
    • The current time in ISO 8601 format (preferably in GMT, but as long as the offset is specified it'll work), given as timestamp=2008-11-25T22:39:16Z. The time will need to be within 15 minutes of the time on the server.
    • The authstr, which is an MD5 hash of your token and the elements of your request (except for the authstr itself, obviously).  To get the string, concatenate all of your GET and POST variables together in alphabetical order, including user and timestamp. Then concatenate that string to the end of your token, and take the MD5 hash of that string to get your authstr.

      Code to calculate the authstr should be something like this:

      sub calc_authstr {
         my $params = shift; # a hash of all your GET and POST parameters and values
         my $token = shift; # your token
         my $str = $token; # the string to MD5
         foreach (sort keys %{$params}){
             # stick them together
             $str .= $_ . $params->{$_};
         return md5_hex($str);

  3. Assuming that you assembled your authstr correctly, then putting those three things into your request should authenticate you for that request. A new authstr will have to be generated every request - they don't carry across.

Note: Credit where credit is due; this authentication scheme is inspired by, but not identical, to the one used by Voxel hAPI.

comments powered by Disqus