API documentation

← Towards the developers space

Authentication for desktop applications

Authentication for desktop applications is similar to authentication for web applications web.

Setup your application

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

  • api_key: 0123456789abcdef0123456789abcdef
  • secret: 0a2b3c4d5e6a7b8d

Steps of authentication

Contrary to web applications, desktop applications don't have any callback URL and should request a frob before creating an authorization link.

1. Request a frob

Use the auth.getFrob API method to get a frob. This request must be signed.


2. Redirect the user to the authorization page

Build an authorization link with frob as follows:

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

Go to the chapter about permissions for more details about this link parameters.



Then invite the user to open this URL and to go back to your application. For example:

My fantastic application
My fantastic application needs your authorization to read or modify your content on ipernity.

Authorization is a simple process that takes place in your web browser. After completing authorization, go back to this window then start using this application.


You need to be signed in to authorize this application.

3. Get a token from the frob

Once this authorization button is clicked by the user, propose a new screen to complete authorization. For example:

My great application
Go back to this window after giving permission to My fantastic application.

Once done, click the "Complete authorization" button and start using this program.


You can revoke permissions to this application at any time from your account settings on ipernity.

After completing authorization by the user, you'll be able to get an authentication token from the frob. So use the auth.getToken API method. This call must be signed.

In our example, here are the parameters sent to /api/auth.getToken/xml:

  • api_key: 0123456789abcdef0123456789abcdef
  • frob: 123456789-0ad5e2a80ad5e2a8
  • api_sig: 8ae34e6d4abe8384cf45c70f9b90c657
 <permissions doc="read" blog="none" network="none" user="none" />
 <user user_id="123" username="james007" realname="James Bond"/>

4. Make an API call in authentication mode

You can now make API calls in authentication 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.).