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".
First, you'll need to select OAuth 1
as your auth type, and then provide the required parameters:
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.
We attempt a 3 legged OAuth 1 process that has 3 high level steps:
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
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>
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>
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
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; } }
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.