Zooomr API: Authentication API

Authentication Prerequisites

Any applications wishing to use the Zooomr Authentication API must have already obtained a Zooomr API Key?. In addition, the API Key must have the following settings configured:

  • Application Title
  • Application Description
  • Application About URL (recommended, but optional)

When an API Key is blessed by Zooomr, it is assigned a special token called a 'Shared Secret'. This secret token is used in the signing process, detailed in section labeled Signing Calls.

Once an application has its blessed API Key and Shared Secret, it can then use one of two authentication methods: Web-based or non-Web-based. Each application key may only be associated with one authentication method at a time.

Web-based Authentication

For Web-based authentication, the developer must register a Callback URL? for the application. The purpose of this URL is explained in the section labeled Authentication for Web-based Applications.

Non-Web-based Authentication

For non-Web-based authentication, there are no additional steps required.

Authentication for Web-based Applications

When a Web-based application needs to authenticate a user, it should redirect the user to the following URL:

http://www.zooomr.com/services/auth/?api_key=[api_key]&perms=[perms]&api_sig=[api_sig]

Here's a breakdown on what is included inside of the above URL:

  • api_key is the application's API Key
  • perms sets a desired level of permission for actions which the application wants to perform on behalf of the user. More on this in the section labeled Authentication Permissions.
  • api_sig is a signature, as further explained in the section labeled Signing Calls.

Should the user not be currently logged in to Zooomr, they are first asked to do so.

Zooomr then asks the user if they would like to authenticate against this application. The application's name and description are displayed, along with a set of description regarding permissions the application wishes to have. The user is then prompted to grant all or none of the requested permissions.

If the user grants access to their account at the specified access level, they are then automatically redirected back to the application using the Callback URL previously registered for the API key. The Callback URL will have the following appended to it:

?frob=[frob]

The application should then immediately call the API method zooomr.auth.getToken, passing along their API Key with the frob received in through the transaction. This call should also be signed with their shared secret (see the section labeled Signing Calls). If the request is valid, the response from this method will include an authentication token for use in future calls to the Zooomr API, along with the granted permissions.

Renewing Web-based Authentication Tokens

To renew an authentication token, a Web-based application can simply redirect the user to the Zooomr Authentication URL as specified above. If the user is logged in to Zooomr and has already authenticated against the Application before with the requested permissions (or a subset of the permissions granted) AND the token has not expired then the user is redirected through the permission granting page to the Application's Callback URL with a frob. The Application must then call zooomr.auth.getToken to retrieve the new token.

Important Implementation Guidelines

  • If an application is to store Authentication information inside of cookies, it should only be stored for a single session.
  • Users must always be provided with a 'logout' link.

Authentication for non-Web-based Applications

When a Desktop-based or other non-browser-specific application needs to authenticate a user, it should first call the API method zooomr.auth.getFrob, which requires signing (see the section labeled Signing Calls). The response to the method call contains a 'frob' which will then be used to build a url to that the user will be sent to in order to continue authentication.

http://www.zooomr.com/services/auth/?api_key=[api_key]&perms=[perms]&frob=[frob]&api_sig=[api_sig]

The parameters similar to those described in the section labeled Authentication for Web-based Applications.

When the user grants permissions, instead of redirecting the user to a Callback URL, Zooomr displays a completion screen that instructs the user to return to the Application.

When a user returns to the application and asks to continue with authentication, the application should call the API method zooomr.auth.getToken, passing along their API Key and frob (this call must be signed - please see the section labeled Signing Calls). If the request is valid, the response from this method will include an authentication token for use in future calls to the Zooomr API, along with the granted permissions.

Renewing Non-Web-based Authentication Tokens

To check if a token needs renewing or has enough permissions, the application should always call the zooomr.auth.checkToken method. Should the token be invalid or lack relevant permissions, then the application should request a new token using the same sequence as if it were to request a fresh token.

Important Implementation guidelines

  • User profile data (which includes auth tokens) should be stored in the local user's 'profile' provided by the OS, so that machines with multiple profiles/users can switch between them without sharing authentication data. Under Windows, this could correspond to storing data in the registry under HKEY_CURRENT_USER, or if the user were running OSX or a *NIX, in the user's home directory.
  • Users must always be provided with a way to clear any authentication and/or privacy data.

Authentication Permissions

As a rule of thumb, an application should never request more permissions than it needs to operate. The permissions field is a opaque string, representing a specific permission level. Each level implies the level below it. Possible permissions are:

  • read -> permission to read private information
  • write -> permission to add, edit and delete object (photos, etc.) metadata (includes read )
  • delete -> permission to delete objects (photos, etc.) (includes write and read )

For example, the permission write allows an application to read and write on behalf of the user, whereas delete would allow all three: delete , write and read .

Authentication Frobs

Each Authentication Frob represents a specific tie between a user and an Application's API Key. A single frob can only be used with the Application key that created it.

Authentication Frobs are only valid for 60 minutes from the time it is created, or until the application calls zooomr.auth.getToken -- whichever comes sooner.

Please Note: Only one (1) Authentication Frob per application per user will be valid at any one time. Applications must be flexible enough to deal with expired and invalid authentication frobs and be able reissue them when required.

Authentication Tokens

Each authentication token represents a specific tie between a user and an Application's API Key. The token can not be used with any other Application keys.

An application can check the status of an Authentication Token by calling the API method zooomr.auth.checkToken, which will return the validity of the token, along with information regarding the user it authenticates and any permissions that have been granted.

As an advanced feature, Authentication Tokens can be time sensitive in that when a user authenticates against the application they can choose a timeframe for the token to expire. Expiration can be set to One (1) Hour or Never.

Please Note: Only one (1) Authentication Token per application per user will be valid at any one time. Applications must be flexible enough to deal with expired and invalid authentication tokens and be able renew them when required.

Finally, all API calls using an Authentication Token must be signed (please see the section labeled Signing Calls).

Signing Calls

All API calls using an Authentication Token must be signed. In addition, calls to the zooomr.auth.* methods and any/all redirections to the auth page on Zooomr must also be signed.

The Signing Algorithm is as follows:

  • Sort your argument list into alphabetical order based on the parameter key (e.g. foo=1, bar=2, baz=3 sorts to bar=2, baz=3, foo=1)
  • Concatenate the Shared Secret and argument key-value pairs (e.g. SECRETbar2baz3foo1)
  • Calculate the md5() hash value of this string as a hexidecimal string
  • Append the hash value to the argument list with the name api_sig (e.g. api_sig=d25100ff30af7ad87f5da8a509c4b6a5)