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

Permissions

Applications must ask the permission to access, modify or delete data.

Applications permissions

Applications can request permissions on the following items:

  • Photos/video/docs: permissions for photos/videos/docs posted.
  • Articles: permissions for articles.
  • Contact: permissions on the contacts.
  • Profile: permissions on the user's profile.
The requested permission can be:
  • read : grants read-only access to user's items, even private.
  • write : permits the modification of the user's items (and also grants read permission.).
  • delete : permits the deletion of the user's items (and also grants write and read permission.).

Request which permissions?

Permissions your application must request depend on the API methods you intend to use (this is indicated for each method.) Users will decide whether or not to grant permissions to your application. Don't request permissions that aren't used or don't make sense.

When your application does API calls without special permission, only public items will be returned with the same restrictions as an anonymous visitor.

How to request permission?

A permission is requested on an authorization web page http://www.ipernity.com/apps/authorize.

Build a connection link

A connection URL is built like this: 

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

  • [api_key] : your API key.
  • [api_sig] : this request signature built using your secret.
  • [perm_doc] : the requested permission for photos/videos/docs. (read/write/delete).
  • [perm_blog] : the requested permission for the blog. (read/write/delete).
  • [perm_post] : the requested permission for articles. (read/write/delete).
  • [perm_network] : the requested permission for the contacts (read/write/delete).
  • [perm_profile] : the requested permission for the user's profile (read/write).

For example, here is an authorization link that requests permission to modify photos/videos/docs: 

http://www.ipernity.com/apps/authorize?api_key=6fa87ba500002712bd4eed6020f3bd72&perm_doc=write&api_sig=46baf59c7e766e1a632e1769849d839c

Redirect the user to the page above to obtain the requested permissions.

It's often necessary to warn the user (avoiding surprise) when redirecting him.

Link of connection with a frob

In the case of an authentication request for a desktop application, a frob parameter will have to be added. 

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

Authorization page

This page presents the user with the following information:

  • The name of your application and its optional subtitle.
  • The application description in the user's language if available.
  • The name of the application developer
  • The website URL, when filled in.
  • Permissions requested by the application

Once the application is authorized, it will be added to the list of authorized applications in the user's account settings.

Check granted permissions

auth.getToken and auth.checkToken methods let you retrieve and check the permissions granted to your application by a user.

Your application can request new permissions at any time by providing the user with a new connection link.