API documentation

← Towards the developers space

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.



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:
 <permissions doc="read" blog="none" network="none" user="none" />
 <user user_id="123" username="007" realname="James Bond"/>

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.)