Flickr Authentication API
Web Applications How-To

This is a simple step-by-step guide to creating a web-based application using the Flickr Authentication API. A full spec of the API can be found here. See also: desktop 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 Web Application for your Authentication Type. Fill out the Callback URL field - it should point to a page on your site which the user will be sent to after they have completed the auth process. We'll see how that works in step 4.

3. Create a login link

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 create a login url. The kit will also handle making authenticated, signed API calls. Please check the documentation for your API kit for details.

If you're not using an API kit, then construct the url as follows:

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

[api_key] is the API key you created in step 1. [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, our API key is 9a0554259914a86fb9e7eb014e4e5d52, our shared secret is 000005fab4534d05 and we want to request write permissions.

So our signature string is 000005fab4534d05api_key9a0554259914a86fb9e7eb014e4e5d52permswrite. This is secret + 'api_key' + [api_key] + '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=write&api_sig=a02506b31c1cd46c2e0b6380fb94eb3d

4. Create an auth handler

When users follow your login url, they are directed to a page on flickr.com which asks them if they want to authorize your application. This page displays your application title and description along with the logo, if you uploaded one.

When the user accepts the request, they are sent back to the Callback URL you defined in step 2. The URL will have a frob parameter added to it. For example, if your Callback URL was http://test.com/auth.php then the user might be redirected to http://test.com/auth.php?frob=185-837403740 (The frob value in this example is '185-837403740').

5. Convert frob to a token

Your auth handler page needs to take this frob and 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_key9a0554259914a86fb9e7eb014e4e5d52frob185-837403740methodflickr.auth.getToken

When we take the MD5 sum of this string and get 6537faf7068cb4b756b1c49efb2575f7. 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>67-76598454353455</token>
	<perms>write</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_token67-76598454353455methodflickr.blogs.getList

The MD5 sum of this, our signature, is d8c5bd551143db42f9b2c4a8fb56abcf.

Every authenticated call requires both the auth_token and api_sig arguments.