Flickr Authentication API
Web Applications 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:
[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:
- read - permission to read private information
- write - permission to add, edit and delete photo metadata (includes 'read')
- delete - permission to delete photos (includes 'write' and 'read')
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
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:
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
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:
- method = flickr.auth.getToken
- api_key = 9a0554259914a86fb9e7eb014e4e5d52
- frob = 185-837403740
We put these together in alphabetical order, prepending the shared secret and we get:
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
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:
- method = flickr.blogs.getList
- api_key = 9a0554259914a86fb9e7eb014e4e5d52
- auth_token = 67-76598454353455
So our signature string is:
The MD5 sum of this, our signature, is
Every authenticated call requires both the