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.

http://api.ipernity.com/api/auth.getFrob?api_key=[api_key]&api_sig=[api_sig]

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.

Example:

http://www.ipernity.com/apps/authorize?api_key=6fa87ba500002712bd4eed6020f3bd72
&frob=454-712bd4eed6&perm_doc=write&api_sig=b1bd22c5e20d326425574a9c522c248c

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 docs in ipernity.

Authorization is a simple process that takes place in your web browser.\n 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 windows 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 page in 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

Outputs:

<auth>
 <token>987654321-e5a5b9c3d5a77eab</token>
 <permissions doc="read" blog="none" network="none" user="none" />
 <user user_id="123" username="james007" 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 authenticated mode must be signed (api_sig parameter).

Help / API / Documentation