Flickr Authentication API

1. Introduction

This is RELEASE 1 of the flickr authentication API specification - $Revision: 1.19 $.

1.1. Authors

2. Authentication prerequisites

Any applications wishing to use the flickr authentication api must have already obtained a flickr API key. In addition, they must configure the following settings, attached to the API key:

A 'shared secret' for the api key is then issued by flickr. This secret is used in the signing process, detailed in section 8.

Applications can then choose one of two authentication methods - web based or non-web based. Each application key may only be associated with a single authentication method.

2.1. 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 section 3.

2.2. Non-web based authentication

For non-web based authentication, there is no additional setup required.

2.3. Mobile authentication

In the future, flickr may offer an additional authentication mechanism for mobile applications.

3. 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://flickr.com/services/auth/?api_key=[api_key]&perms=[perms]&api_sig=[api_sig]

perms is a desired level of permission for actions which the application wants to perform on behalf of the user. These are described in section 5. api_sig is a signature, as explained in section 8.

If the user is not currently logged in to flickr, they are first asked to do so.

Flickr then asks the user if they wish to authenticate against this application. The application name and description are displayed, along with a description of permissions the application wishes to have. The user can then choose to grant all or none of the requested permissions. If the user grants the permssions, then they are redirected back to the application using the callback url previously registered for the used API key. The callback url will have the following appended:

?frob=[frob]

The application should then call the API method flickr.auth.getToken, passing along their api key and the passed frob, and signed with their shared secret (see section 8). The response then includes an authentication token for use in future API calls, along with the granted permissions.

3.1. Renewing web based authentication tokens

To renew an authentication token, a web based app simply redirects the user to the flickr auth url again. If the user is logged in to flickr and has already authenticated against this app with the requested permissions (or more permissions - so long as the requested subset has been granted) and the token hasn't expired then they are redirected straight back to the application with a frob pointing to the existing authentication token. If the token has expired or extra permissions are requested, the user is prompted as before for renewal.

3.2. Implementation guidelines

Authentication cookies should only be stored for a single session.

Users must be provided with a 'logout' link.

4. Authentication for non-web based applications

The first step for desktop and other non-browser-based applications is to call the API method flickr.auth.getFrob, which requires signing (see section 8). The response to the method call contains a 'frob' which should then be used to build a url to direct the user to the following url (opening in the system's default browser):

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

Other parameters are as described in section 3. When the user grants permissions, instead of redirecting the user offsite, flickr displays a screen saying 'permissions granted - return to your app'.

The application, when told by the user that they have authenticated, should call the API method flickr.auth.getToken, passing along their api key and frob (the call must be signed - see section 8). The response then includes an authentication token for use in future API calls, along with the granted permissions.

4.1. Renewing non-web based authentication tokens

To check if a token needs renewing or has enough permissions, the app should call the flickr.auth.checkToken method. If the token is invalid or lacks relevant permissions, then the applications should request a new token using the same sequence as to request a fresh token.

4.2. Implementation guidelines

User profile data (including auth tokens) should be stored in the local user's 'profile', so that machines with multiple profiles/users can switch between them without sharing auth data. Under windows this may correspond to storing data in the registry under HKEY_CURRENT_USER, and in the user's home directory on OSX/Unix.

Users must be provided with 'logout' functionality.

5. Authentication permissions

An application should never request more permissions than it needs to operate. The permissions field is a string, representing the permission level. Each level implies the level below it. Possible permissions are:

For example, the permission w allows an application to read and write on behalf of the user.

6. Authentication tokens

Each authentication token is specific to a user and an application's api key, and can only be used with that key. An application can check the status of an auth token by calling the API method flickr.auth.checkToken, which will return the validity of the token, along with the user it authenticates and the premissions it is granted.

Authentication tokens can be set to expire by the user when they authenticate against the application. This is an advanced feature, hidden by default. Options are 1 hour and never. This may be set for different applications by policy in the future.

Only one authentication token per application per user will be valid at any one time. Applications must deal with expired and invalid authentication tokens and know how to renew them.

All API calls using an authentication token must be signed (see section 8).

7. Authentication frobs

Each authentication frob is specific to a user and an application's api key, and can only be used with that key.

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

Only one authentication frob per application per user will be valid at any one time. Applications must deal with expired and invalid authentication frobs and know how to renew them.

8. Signing

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

The process of signing is as follows.

9. Examples

9.1. Web based app

Our web based app has the api key '1234567890'. It has already registered a callback url for this key - 'http://viewr.com/auth.php'.

9.2. Non-web based app

Our desktop app has the api key '987654321'. It has been assigned 'foobarbaz' as it's auth secret.