Authentication How-To

Givealink provides third-parties with a secure means of creating user sessions over the Givealink API using the OAuth protocol. This allows a deeper integration between Givealink services and third-parties consumers that want access to protected Givealink data. All write API methods require authentication.

Givealink is an OAuth Service Provider and it is fully compliant with the OAuth specifications. It means that the complete reference for the user authentication and access to protected data is the OAuth Core Specifications document. This how-to provides an easy-to-read description that does not substitute the full specification.

Below, a scheme summarizes the basic steps of the authentication process:

Givealink provides authentication methods to the following URLs:

1. Get an Unauthorized Request Token:   http://givealink.org/oauth/request_token
2. Obtaining User Authorization:   http://givealink.org/oauth/authorize
3. Get an Access Token:   http://givealink.org/oauth/access_token

Each of these methods requires a set of parameters as specified in the OAuth documentation and summarized in the rest of this how-to.

1. Get an Unauthorized Request Token

To get an Unauthorized Request Token the Consumer has to call the http://givealink.org/oauth/request_token method specifying the following parameters:

For example, let us supose that parameters are passed via the HTTP Authorization header (see here for details) :

Authorization:  OAuth
              oauth_consumer_key="0685bd9184jfhq22",
              oauth_signature_method="HMAC-SHA1",
              oauth_signature="wOJIO9A2W5mFwDgiDvZbTSMK%2FPY%3D",
              oauth_timestamp="137131200",
              oauth_nonce="4572616e48616d6d65724c61686176",
              oauth_version="1.0",
              oauth_callback="http://example.com"

In a positive case, Givealink will generate a token and it will send back to the Consumer, with the following parameters in the HTTP response body:

For example:

oauth_token=HrjVt1AO64qXhXliXIww&oauth_token_secret=SbegYl2vcVL7GNjMjHcnvbKHA5jETWnkVh5VnQlJ&oauth_callback_confirmed=true

Obtaining User Authorization

The Consumer must obtain approval from the User by directing the User to the Service Provider through an HTTP GET request to the Service Provider's User Authorization URL http://givealink.org/oauth/authorize with the following parameter:

http://givealink.org/oauth/authorize?oauth_token=HrjVt1AO64qXhXliXIww

After the User does or does not provide authorization to the Consumer, the Service Provider redirects to the oauth_callback url, in the case of web based applications, or displays a resume, in the case of mobile/desktop applications. In both cases, the Service Provider provides the following parameters:

Get an Access Token

The Request Token and Token Secret must be exchanged for an Access Token and Token Secret. To request an Access Token, the Consumer makes an HTTP request to the Service Provider's Access Token URL containing the following parameters:

If successful, the Service Provider generates an Access Token and Token Secret and returns them in the HTTP response body. The response contains the following parameters:

The Access Token and the Access Secret are used to consume protected resources according to the schema described in the developer guide and in the specifications.