Lesson 23: Connecting to an external API with OAuth authorization

From VZ Developer Wiki
Jump to: navigation, search

General Guidelines | XML Specification | Features | Views | JavaScript API | REST API | Tutorials | OAuth

Lesson 22: Posting a status update for an user Back to overview

This functionality is in development at the moment and will be available from Jan, 17.

This tutorial shows how you can connect to any external API that is secured through basic three legged OAuth from your gadget. As an example we will use the Twitter API, but this tutorial works the same with any other service provider.

Registering your gadget at Twitter

The first thing you have to do is registering your gadget at Twitter to gain your consumer tokens to access the API.

Go to http://dev.twitter.com/apps/new and enter a name and description for your application. At Twitter you have to choose the application type "Browser" and enter any callback URL. The callback URL you are specifiyng will be overwritten by the correct callback URL by the gadget server later on.

Twitter Create Application.png

After that you will receive your consumer key and consumer secret. Enter these tokens for your gadget in our gadget sandbox. You also need to specify a service name to identify these tokens in your gadget later on. Note that it may currently take up to 30 minutes for your new tokens to be available in the sandbox and on the production servers.

VZ enter OAuth credentials.png

Adding the OAuth endpoints

In your gadget you now have to specify the OAuth endpoints for the Twitter API. Add these lines to the ModulePrefs section of your gadget XML (see Gadgets_XML#ModulePrefs.2FOAuth for a detailed specification):

  <Service name="MyTwitter">
    <Request url="https://api.twitter.com/oauth/request_token" param_location="uri-query" />
    <Access url="https://api.twitter.com/oauth/access_token" param_location="uri-query" />
    <Authorization url="https://api.twitter.com/oauth/authorize" param_location="uri-query" />

You also have to add the Twitter Endpoint to the list of whitelisted backend endpoints for your gadget, so that our Proxy Server won't reject your requests (see Gadgets_XML#ModulePrefs.2FAllowedDomain):

<AllowedDomain name="api.twitter.com" />

In order to complete the full three-legged OAuth flow the user has to enter his credentials and authorize your client at the Twitter website. Typically this is done by opening a popup from the client page. To help you with this popup handling the gadget server provides a feature that you should include in your gadget:

<Require feature="oauthpopup" />

Requesting the API

When you want to request the Twitter API now, all you have to do is to issue a standard proxied request with the makeRequest() method:

var fetchData = function() {
  var onOpen = function() {};
  var onClose = function() { fetchData(); };
  var params = {};
    function(response) {
      if (response.oauthApprovalUrl) {
        var popup = new gadgets.oauth.Popup(

    }, params 


The JavaScript will make a request to the Gadget Proxy Server with the Twitter API URL as a target. If there is an access token available for the current user, the proxy will forward the request directly to the API, otherwise it will start the OAuth handshake process and return an oauthApprovalUrl which points to the OAuth Authorization endpoint of the API. This URL will be opened with the help of the gadgets.oauth.Popup class and after it has been closed by the Proxies Authorization callback, the gadget reissues the request to the proxy which now has an access token for the current user in place.

For a more detailed description on the gadgets.oauth.Popup feature see Gadgets.oauth.Popup_(v0.9).

  • Lesson 23: Connecting to an external API with OAuth authorization