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 with OAuth

This page is only available in english.

The OAuth protocol enables websites or applications (Consumer) to access Protected Resources from ipernity via the API, without requiring Users to disclose their ipernity credentials to the Consumer.

Here is the three OAuth specific URLs:

  • https://www.ipernity.com/apps/oauth/request
    Request Token URL: to obtain an unauthorized Request Token.

  • https://www.ipernity.com/apps/oauth/authorize
    User Authorization URL: to obtain User authorization for Consumer access.

  • https://www.ipernity.com/apps/oauth/access
    Access Token URL: to exchange the User-authorized Request Token for an Access Token.

We fully support the OAuth 1.0 specification. We suppport the OAuth 1.0a specification (only oauth_verifier is not supported).

Glossary

  • Consumer: A website or application that uses OAuth to access ipernity on behalf of the User.
  • Protected Resource(s): Data controlled by ipernity, which the Consumer can access through authentication.
  • Consumer Key: This is a unique key provided free of charge and that identifies the Consummer application.
  • Consumer Secret: A secret use by the Consumer to sign its API requests.
  • Request Token: A value used by the Consumer to obtain authorization from the User, and exchanged for an Access Token.
  • Access Token: A value used by the Consumer to gain access to the Protected Resources on behalf of the User, instead of using the User's ipernity credentials.
  • Token Secret: A secret used by the Consumer to establish ownership of a given Token.
  • Nonce: The term nonce means "number used once" and is a unique and usually random string that is meant to uniquely identify each signed request.
  • OAuth Protocol Parameters: Parameters with names beginning with oauth_.

Signing Requests

Each requests must be signed accordingly to the OAuth specification. Ipernity supports HMAC_SHA1 and MD5 as signature method:

  • The HMAC-SHA1 signature method uses the HMAC-SHA1 signature algorithm as defined in [RFC2104] where the Signature Base String is the text and the key is the concatenated values (each first encoded per Parameter Encoding) of the Consumer Secret and Token Secret, separated by an '&' character (ASCII code 38) even if empty.
  • For signing with the MD5 method, the Consumer Secret and Token Secret (each first encoded per Parameter Encoding), separated by an '&' character (ASCII code 38) even if empty, MUST be added to the end of the Signature Base String.

Steps of authentication

OAuth Authentication is done in three steps:

  1. The Consumer obtains an Request Token.
  2. The User authorizes the Request Token.
  3. The Consumer exchanges the Request Token for an Access Token.

1. Get a Request Token

Sends an HTTP request to the Request Token URL (https://www.ipernity.com/apps/oauth/request). the HTTP method for this request can be HTTP HEAD, HTTP POST or HTTP GET. The request MUST be signed and contains the following parameters:

  • oauth_consumer_key: The Consumer Key.
  • oauth_signature_method: The signature method the Consumer used to sign the request (MUST be HMAC_SHA1 or MD5).
  • oauth_signature: The signature.
  • oauth_timestamp: The timestamp.
  • oauth_nonce: the nonce.
  • oauth_version: OPTIONAL. If present, value MUST be 1.0 or 1.0a.
  • oauth_callback: OPTIONAL (can be provided in the next step). An absolute URL to which ipernity will redirect the User back when the User Authorization step is completed. The callback URL MAY include Consumer provided query parameters, ipernity retain them unmodified and append the OAuth parameters to the existing query.
https://www.ipernity.com/apps/oauth/request?oauth_consumer_key=[consumer_key]&oauth_signature_method=[signature_method]&oauth_signature=[signature]&oauth_timestamp=[timestamp]&oauth_nonce=[nonce]

2. Redirect the user to the authorization page

In order for the Consumer to be able to exchange the Request Token for an Access Token, the Consumer MUST obtain approval from the User by directing the User to ipernity. The Consumer constructs an HTTP GET request (not signed) to ipernity's User Authorization URL (https://www.ipernity.com/apps/oauth/authorize) with the following parameter:

  • oauth_token: The Request Token obtained in the previous step.
  • oauth_callback: OPTIONAL (can be provided in the previous step). An absolute URL to which ipernity will redirect the User back when the User Authorization step is completed. The callback URL MAY include Consumer provided query parameters, ipernity retain them unmodified and append the OAuth parameters to the existing query.
  • permissions parameters: Go to the chapter about permissions for more details about this link parameters.
https://www.ipernity.com/apps/oauth/authorize?oauth_token=[auth_token]&perm_doc=[perm]

Please note that once authenticated, the consumer callback URL will be called with the request token (oauth_token=xxx) added to it.

3. Exchange the Request Token for an Access Token

To request an Access Token, the Consumer makes an HTTP request to ipernity’s Access Token URL (https://www.ipernity.com/apps/oauth/access). The HTTP method for this request can be HTTP HEAD, HTTP POST or HTTP GET. The request MUST be signed and contains the following parameters:

  • oauth_consumer_key: The Consumer Key.
  • oauth_token: The Request Token obtained previously.
  • oauth_signature_method: The signature method the Consumer used to sign the request (MUST be HMAC_SHA1 or MD5).
  • oauth_signature: The signature.
  • oauth_timestamp: The timestamp.
  • oauth_nonce: the nonce.
  • oauth_version: OPTIONAL. If present, value MUST be 1.0 or 1.0a.
https://www.ipernity.com/apps/oauth/access?oauth_consumer_key=[consumer_key]&oauth_token=[auth_token]&oauth_signature_method=[signature_method]&oauth_signature=[signature]&oauth_timestamp=[timestamp]&oauth_nonce=[nonce]

Make an API call in authenticated mode

After successfully receiving the Access Token and Token Secret, the Consumer is able to access the Protected Resources on behalf of the User. The HTTP method for this request can be HTTP POST or HTTP GET. The request MUST be signed and contains the following parameters:

  • oauth_consumer_key: The Consumer Key.
  • oauth_token: The Access Token.
  • oauth_signature_method: The signature method the Consumer used to sign the request (MUST be HMAC_SHA1 or MD5).
  • oauth_signature: The signature.
  • oauth_timestamp: The timestamp.
  • oauth_nonce: the nonce.
  • oauth_version: OPTIONAL. If present, value MUST be 1.0 or 1.0a.
  • Additional parameters: Any additional parameters required by the api method called.

Please note that only the OAuth specific parameters can be passed through the HTTP HEADERS. But all api method specific parametres MUST BE passed by HTTP POST or HTTP GET.

Let's consider for instance the docs.tags.add method. Parameters must be:

  • oauth_consumer_key: efd6fbe940008a9271E3501e449
  • oauth_token: 10d294e0595c4c1ad
  • oauth_signature_method: MD5
  • oauth_signature: O6VcmSELbv60HfKuqKFgjg
  • oauth_timestamp: 1257862574
  • oauth_nonce: 4af975aecd544
  • doc_id: 1234
  • keywords: "nice car"