API documentation

← Towards the developers space
About the API
Getting started
Data encoding, signature
Permissions
Authentication for web application
Authentication for desktop application
Authentication with OAuth
API input formats
API output formats
Data formats
Write an API kit

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. 

https://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:

https://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: 

https://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 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
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 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.).