OAuth V1#

The flow we respect matches Twitter's and Trello's implementation of the 3-legged oauth flow.

Note that OAuth v1 is not officially supported on Zapier; we highly recommend using OAuth 2 if possible!

That said, because OAuth v1 has been a popular authentication mechanism, we have a sample implementation if you want to try it, respecting OAuth v1 "revision a".

Initial Setup:#

First, you'll need to select OAuth v1 as your Authentication Type. In most cases you can continue with the default Authentication Fields. The final step is to configure OAuth V1:

Capture extra data from token response

If your app returns extra data through the token response (user id for example) you can grab those extra parameters using the Extra Requested Fields option.

How we authenticate with your OAuth service#

We attempt a 3 legged OAuth 1 process that has 3 high level steps:

1. Obtain temporary oauth_token and oauth_secret from your app
2. Get user to authorize Zapier access to your app
3. Exchange the temporary oauth_token for an authorized oauth_token

1. Requesting Temporary Credentials From Your App:#

When a user goes to add a new account for your app, we make a request behind-the-scenes to ask your app for a request token and secret. Your app should respond back with a valid oauth_token and oauth_token_secret. Additionally, our request contains an oauth_callback URL that your app will use in a later step.

The signed POST request to your application's request_token_url will look like this:

POST https://example.com/api/1.0/oauth/request_token
Authorization: OAuth 
oauth_nonce="ZAPIER-GENERATED-NONCE", 
oauth_callback="ZAPIER-OAUTH-CALLBACK", 
oauth_signature_method="HMAC-SHA1", 
oauth_timestamp="ZAPIER-GENERATED-TIMESTAMP", 
oauth_consumer_key="<Your consumer key>", 
oauth_signature="ZAPIER-GENERATED-SIGNATURE", 
oauth_version="1.0"

Your app should validate the request and return with the temporary response token, like so:

oauth_token_secret=TEMP-OAUTH-TOKEN-SECRET&oauth_token=TEMP-OAUTH-TOKEN&oauth_callback_confirmed=true

2. Redirecting the User to Your App:#

With token in hand, we redirect the user to the authorization_url you provided, so that they can grant access to Zapier.

302 https://example.com/api/v1/oauth/authenticate?oauth_token=<oauth_token>

3. Redirecting the User Back to Zapier:#

After the user clicks allow, your app redirects the user to oauth_callback (from Step 1), along with an oauth_verifier parameter in the query string.

302 <oauth_callback>?oauth_verifier=<oauth_verifier>

4. Exchanging Temporary Credentials for Token Credentials:#

We use that oauth_verifier to make a POST to the access_token_url you provided.

POST https://example.com/api/1.0/oauth/access_token \
    -H Accept: application/json \
    -d 'consumer_key=<consumer_key>&
        consumer_secret=<consumer_secret>&
        oauth_verifier=<oauth_verifier>&
        oauth_token=<oauth_token>&
        oauth_token=<oauth_token_secret>

Your service should then provide an access_token and access_token_secret, along with any extra parameters that you may have included in the optional Capture extra data from token response step.

While we ask for a JSON response, the response can be JSON, XML or query string encoded. For example, any of the below are valid responses:

With Content-Type: application/json:

{
  "oauth_token": "1234567890abcdef",
  "oauth_token_secret": "1234567890abcdef",
}

With Content-Type: application/xml:

<AnyRootElem>
  <oauth_token>1234567890abcdef</oauth_token>
  <oauth_token_secret>1234567890abcdef</oauth_token_secret>
</AnyRootElem>

With Content-Type: text/plain:

oauth_token=1234567890abcdef&oauth_token_secret=1234567890abcdef

5. Using the Token Credentials#

We sign all requests using your secret and the new oauth_token and oauth_token_secret. We're talking standard HMAC-SHA1, RSA is not supported. However, you can use scripting to modify request parameters (including headers) as you see fit.

For example, if a POST request to your API expects Content-Type:application/x-www-url-form-encoded instead of the standard application/x-www-form-urlencoded then you can use a custom script to modify the request that we make. In an app with a trigger create_ticket the Scripting API would look like so:

var Zap = {
    create_ticket_pre_write: function(bundle) {
        bundle.request.headers['Content-Type'] = 'application/x-www-url-form-encoded';
        return bundle.request;
    }
}

Example:#

We highly recommend looking at each of Bitbucket's, Twitter's and Trello's authentication documentation for some great examples of how OAuth 1a can be implemented. Our system is designed to match their industry standard implementation pattern. Additionally, oauth1a spec and oauth bible can be extremely useful in understanding the 3 legged oauth flow.