PmWiki | UserAuthentication / Authentication API

All API calls using an authentication token must be signed. In addition, calls to the cc.auth.* methods and redirections to the auth page on cobocards must also be signed.

With the API key, you'll also receive a shared secret that is used to sign (on your end) and verify (on our end) requests.

Signing Requests

Let's presume that our shared secret is KILLERBRAIN. To sign a request, you need to:

1. Sort your parameters by key name, so that:

yxz=foo feg=bar abc=baz

becomes:

abc=baz feg=bar yxz=foo

2. Construct a string with all key/value pairs concatenated together:

abcbazfegbaryxzfoo

3. Concatenate the previous result onto your shared secret:

KILLERBRAINabcbazfegbaryxzfoo

4. Calculate the MD5 hash of this string:

md5('KILLERBRAINabcbazfegbaryxzfoo') -> c6a1fd76f4642ae83e21506b3d09804c

We now use this result, c6a1fd76f4642ae83e21506b3d09804c as our api_sig parameter.

User authentication for web-based applications

To authenticate users for your web-based application, construct an authentication URL as follows:

1. Take the authentication service URL:

http://www.cobocards.com/services/auth/

2. Append your api_key. We'll use abc123.

http://www.cobocards.com/services/auth/?api_key=abc123

3. Append a perms parameter. We'll use delete.

http://www.cobocards.com/services/auth/?api_key=abc123&perms=delete

Valid perms values are:

read – gives the ability to read private information.
write – gives the ability to add and modify private information (includes 'read').
delete – gives the ability to delete private information (includes 'read' and 'write').

4. Now sign your parameters as detailed above and append an api_sig.

http://www.cobocards.com/services/auth/?api_key=abc123&perms=delete&api_sig=c6a1fd76f4642ae83e21506b3d09804c

Voilà! An authentication URL. Point your application user at this URL, and CoboCards will:

Ask them to login with their CoboCards credentials, if they're not already logged in, and then...
Ask them if they wish to give your application access to their account (with the permissions you asked for).

If the user authorizes your application, they are then redirected to your callback URL with a frob parameter, like so:

http://www.example.com/cobocards.php?frob=d2bedcd26366fcdf5bfa5744251a526b

If the user declines your application, they are then redirected to your cancel URL

Authentication frobs are valid for 60 minutes from the time it is created, or until the application calls cc.auth.getToken, whichever is sooner.

Your application should now make a call to cc.auth.getToken with a frob parameter as passed to the callback URL. You'll get back an auth token (you use this as the auth_token parameter for all further authenticated API calls) and some user information.

Auth tokens can and do expire, at the least after 10 days from the time it is created. Applications must deal with expired and invalid authentication tokens and know how to renew them.

Done! Simple, right?

User authentication for desktop applications

Desktop application authentication is pretty much identical to the above, but, instead of being redirected to a callback URL with a frob, we first make a call to cc.auth.getFrob and pass the result as a frob parameter in our authentication URL.

So, first of, we call cc.auth.getFrob, and it returns a <frob> element:

<frob>70a3b59ad674a7a1edfcf8a2f6fb0d33</frob>

Authentication frobs are valid for 60 minutes from the time it is created, or until the application calls cc.auth.getToken, whichever is sooner.

Then, construct an authentication URL as follows:

1. Take the authentication service URL:

http://www.cobocards.com/services/auth/

2. Append your api_key. We'll use abc123.

http://www.cobocards.com/services/auth/?api_key=abc123

3. Append a perms parameter. We'll use delete.

http://www.cobocards.com/services/auth/?api_key=abc123&perms=delete

Valid perms values are:

read – gives the ability to read private information.
write – gives the ability to add and modify private information (includes 'read').
delete – gives the ability to delete private information (includes 'read' and 'write').

4. Append your frob from before. We'll use now 123456.

http://www.cobocards.com/services/auth/?api_key=abc123&perms=delete&frob=123456

5. Now sign your parameters as detailed above and append an api_sig.

http://www.cobocards.com/services/auth/?api_key=abc123&perms=delete&frob=123456&api_sig=c6a1fd76f4642ae83e21506b

Voilà! An authentication URL for desktop applications. Point your application user at this URL, and CoboCards will:

Ask them to login with their CoboCards credentials, if they're not already logged in, and then...
Ask them if they wish to give your application access to their account (with the permissions you asked for).

If the user authorizes your application, they are then instructed to return to your application so that the authorization process may be completed.

Your application should now make a call to cc.auth.getToken with a frob parameter (the one you received from cc.auth.getFrob). You'll get back an auth token (you use this as the auth_token parameter for all further authenticated API calls) and some user information.

Auth tokens can and do expire, at the least after 10 days from the time it is created. Applications must deal with expired and invalid authentication tokens and know how to renew them.

That's it!