Authentication for Web applications

The authentication goal is to create a relation between your application and an ipernity user's account. Once this link is created, your application will be able to query the ipernity API on behalf of a user's account using specific permissions.

Setup your application

Here's an example of configuration of your API key for web applications:

• api_key: 0123456789abcdef0123456789abcdef
• secret: 0a2b3c4d5e6a7b8d
• callback: www.yoursite.com/callback.php

Steps of authentication

1. Redirect the user to the authentication page

Build an authentication link as follows:

http://www.ipernity.com/apps/authorize?api_key=[api_key]&perm_doc=[perm] &frob=[frob]&api_sig=[api_sig]

Please read the permissions section for more details about this link parameters.

Please note that api_sig signature calculation must be made without giving a method name.

Example:

http://www.ipernity.com/apps/authorize?api_key=0123456789abcdef0123456789abcdef&perm_doc=write&api_sig=d1ec59737e69c31f7a65ac3cf73c61d0

2. Get back the frob

Once authenticated, the member (its browser) is automatically redirected to your callback URL with the frob parameter.

For example: http://www.yoursite.com/callback.php?frob=123456789-0ad5e2a8

This frob is a disposable one-time use authentication ticket. This ticket remains valid for a few minutes only and must be exchanged for an auth_token authentication token .

3. Exchange the frob for a token

Use the auth.getToken API method to get a token from the frob. This call must be signed.

In that example, parameters sent to the API are:

• api_key: 0123456789abcdef0123456789abcdef
• frob: 123456789-0ad5e2a80ad5e2a8
• api_sig: 8ae34e6d4abe8384cf45c70f9b90c657

So the response will be:

<auth>
 <token>987654321-e5a5b9c3d5a77eab</token>
 <permissions doc="read" blog="none" network="none" user="none" />
 <user user_id="123" username="007" realname="James Bond"/>
</auth>

4. Make an API call in authenticated mode

You can now make API calls in authenticated mode. Simply add the auth_token parameter to the request parameters.

Let's consider for instance the docs.tags.add method. Parameters must be:

• api_key: 0123456789abcdef0123456789abcdef
• auth_token: 987654321-e5a5b9c3d5a77eab
• doc_id: 1234
• keywords: "nice car"

Remember every API call in authentication mode must be signed (api_sig parameter.)