Flickr Authentication API
Desktop Applications How-To

This is a simple step-by-step guide to creating a desktop application using the Flickr Authentication API. A full spec of the API can be found here. See also: web how-to, mobile how-to.

1. Obtain an API key

Every Flickr API application needs to obtain an API 'key'. You can apply for a key here.

2. Configure your key

Once you've been issued a key, it will appear in this list. Click on the 'Not configured' link for your key to start the configuration process.

Note down the Shared Secret - you'll need it in a moment.

Title and Description are required for all applications - the Logo is optional. The Application URL should point to a page on your website describing your application, but is optional. All four of these fields are used when asking a user if they want to allow your application to authenticate them.

Select Desktop Application for your Authentication Type.

3. Request a frob

If you're using an API kit (such as the perl or php bindings - you can see a list here) then you can use the provided function to request a frob. The kit will also handle creating a login url and making authenticated, signed API calls. Please check the documentation for your API kit for details.

Before asking the user to authenticate, you'll need to request a frob to identify the login session. You do this by calling the flickr.auth.getFrob method.

This call requires a signature, in addition to the api_key argument. In our examples, our API key is 9a0554259914a86fb9e7eb014e4e5d52, our shared secret is 000005fab4534d05. To generate a signature, we take our shared secret to prepend it to an alphabetically sorted list of arguments. In this example, our arguments are:

So our signature string is:

000005fab4534d05api_key9a0554259914a86fb9e7eb014e4e5d52methodflickr.auth.getFrob

We then take the MD5 sum of this string and use it as our signature. It should be added as a named argument called 'api_sig'. Our argument list now looks like this:

The response to the method call looks like this:

<frob>934-746563215463214621</frob>

4. Create a login link

You now need to construct a login url as follows:

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

[api_key] is the API key you created in step 1. [frob] is the frob returned in step 3. [perms] is the desired level of account access, as one of the following values:

The permissions needed for each API method call are listed on the API method documentation pages.

[api_sig] is a signature of the other two parameters. Signatures are created using your secret and the other argumnents listed in alphabetical order, name then value. In our example, we want to request read permissions.

So our signature string is 000005fab4534d05api_key9a0554259914a86fb9e7eb014e4e5d52frob934-746563215463214621permswread. This is secret + 'api_key' + [api_key] + 'frob' + [frob] + 'perms' + [perms]. We then take the MD5 sum of the string - this is our [api_sig] value. We can then build our full login URL:

http://www.flickr.com/services/auth/?api_key=9a0554259914a86fb9e7eb014e4e5d52&perms=read&frob=934-746563215463214621&api_sig=06d7a30d8c35769f18f330767e865362

Direct the user to follow this url, then return to your app once they're complete. For example:

5. Convert frob to a token

After launching the login url, your application should display a button to allow users to complete the authentication process. For example:

Your auth handler page needs to then make a regular API method call to the flickr.auth.getToken method. This method call, like all authenticated calls, requires signing. You 'sign' a method by generating a signature based on the arguments to the call. You create the signature string by joining the shared secret to the list of arguments in alphabetical order. In this example, our parameters are:

We put these together in alphabetical order, prepending the shared secret and we get:

000005fab4534d05api_key9a0554259914a86fb9e7eb014e4e5d52frob934-746563215463214621methodflickr.auth.getToken

When we take the MD5 sum of this string and get a5902059792a7976d03be67bdb1e98fd. We then add this value to the argument list, as the named parameter api_sig.

After passing your API key and frob to the method, you should get back a token. The response looks something like this:

<auth>
	<token>45-76598454353455</token>
	<perms>read</perms>
	<user nsid="12037949754@N01" username="Bees" fullname="Cal H" />
</auth>

<perms> should contain the permissions you requested. The <token> element contains the token - this is a value you'll need for making authenticated API calls - it ties a specific user to your application's API key, with a specific level of permissions.

6. Make an authenticated call

Once you have a token, you can make an authenticated method call. In our example we'll call flickr.blogs.getList to get a list of configured blogs for the user.

In addition to the usual method arguments we pass the token, as the named argument auth_token. After adding the token to the argument list, we generate a signature as before. The argument list is:

So our signature string is:

000005fab4534d05api_key9a0554259914a86fb9e7eb014e4e5d52auth_token45-76598454353455methodflickr.blogs.getList

The MD5 sum of this, our signature, is 09f16d79f53bc24f440149af875cdf9d.

Every authenticated call requires both the auth_token and api_sig arguments.