Add authentication with OAuth v2

OAuth v2 authentication is the easiest authentication scheme for users, as it matches the login process they expect from most modern apps. In Zapier integrations with OAuth v2, the user part of authentication typically takes place in full on the app’s own site, helping users easily connect accounts without sharing account credentials or looking up API keys.

When a user adds an app account to Zapier with OAuth v2, they will first see a familar window from that app showing either a login screen or an account selector if they’re already logged in (and the app will send Zapier a request token that will be exchanged for an access token once the user approves access). They can then enter their account credentials confidently since they’re entering them on that app’s own site—and often, users will not need to enter credentials since they’re already logged in. Once they authorize Zapier access, the app will return an access token that Zapier can use to authenticate future API calls.

Which OAuth 2 Flow Type Does Zapier Support?

Zapier implements the “Authorization Code” grant type when you choose OAuth v2. If your OAuth 2 implementation supports refresh tokens, you can optionally configure a “Refresh Token” request.

The Zapier platform does not currently support other grant types. If your integration requires a different OAuth 2 grant type, you’ll need to use another supported authorization type with Zapier such as Session auth or API Key auth. Visit the Zapier Community if you need any guidance on using Session Auth to provide an OAuth flow.

Does Zapier Support OAuth v1?

Not within the Platform UI. If your integration requires OAuth v1 authentication, use the Zapier CLI to build your integration instead.

How to Add OAuth v2 to a Zapier Integration

To add OAuth authentication to a Zapier integration, open your app’s Authentication page in Zapier’s visual builder, then select OAuth v2 from the authentication scheme drop-down.

You’ll need the following items to add OAuth authentication:

• An input form (optional) to gather data from users, such as account team name or site URL for self-hosted apps
• An OAuth application configured in your own app’s settings, where you’ll add Zapier’s OAuth Redirect URL
• A Client ID (may be called Customer or API Key) and Client Secret (may be called Customer or API secret) from your app
• An Authorization URL on your app’s site where users will log in with their account credentials
• A list of API scope(s) (optional) to restrict what Zapier can access
• An Access Token Request URL where Zapier exchanges the request token for an access token
• A Refresh Token Request URL (optional) where Zapier can refresh the access token if it expires, along with an option to have Zapier automatically refresh credentials
• A Test API endpoint where Zapier can make an API call to ensure your user credentials work
• A Connection Label to uniquely identify users’ accounts

Add an OAuth Input Form (optional)

Note: Most apps with OAuth v2 authentication do not need an input form, so unless your API requires data from the user before contacting the authorization URL, or requires URL details to create the authorization URL, you should likely not include an input form.

If your API’s OAuth authentication needs additional details from users before it can display the authorization URL, or Zapier needs to store fields received from your server to use in subsequent API calls, you can add an input form as the first step in your authentication. This will show a form to users with the fields you’ve added before redirecting them to your authorization URL.

To add input fields, click the Add Fields button, then select the type of field you need.

Zapier includes two types of fields: standard fields, which work much like other form fields with Zapier’s input form in triggers and actions, and Computed Fields, which make sure specific fields are returned by your app’s authentication API call response.

For input fields, select the default Field type, then add:

• Key: The internal name for your field, used to reference this field in Zapier API calls. For convenience, use the same key as your API uses for this field. Note: client_id and client_secret are reserved and cannot be used as keys for input form fields.
• Label: A human-friendly name for this field that will be shown to users in the authentication form.
• Required? (checkbox): Check if this field is required for successful authentication.
• Type: (optional) Usually String, but select “Password” to obscure text for secret values.
• Help Text: Add Markdown formatted details on what users should enter in this field, optionally with a link to your site to help users find the data.
• Input Format: (optional) Help users figure out exactly what piece of data you need them to enter. For example, for a subdomain, https://.yourdomain.com/.
• Default Value: (optional) If appropriate, for optional fields, enter text that can be used by default if users don’t enter a value. For required fields, enter text that can be used for authentication, but that won’t be used in subsequent Zap steps.

Add the fields in the order users would expect to see them. You cannot reorder fields, though you can delete fields and add them again if needed.

Computed Fields

If you need to use data received from the auth API response—such as team account names, domains, or subdomains—you can add a Computed Field by selecting the Field Type at the top of the form. Add the field key, using the same field key as your API’s response, and leave the remaining field details blank.

Zapier will then make sure this field is included in the response data, and you can reference it in subsequent API calls. Zapier will show an error if a field marked as computed is not included in the response data. Learn more in our Computed Fields docs.

Once completed, click Continue to save your form and setup OAuth authentication.

Add Zapier Redirect URL to Your App

If you haven’t already, in a different tab or window open your app’s application, integration, or API settings, and add a new application for your OAuth integration with Zapier. From Zapier’s visual builder, copy the OAuth Redirect URL, similar to the one shown above, and add it to your application’s integration settings.

If you ever need to reference Zapier’s redirect URL inside your Zapier integration, use the following code:

{{bundle.inputData.redirect_uri}}

Note: When building a public integration, the redirect URL will change once the app integration is approved for publishing, to be more consistent with your app’s branding. Depending on your API, you may need to add this new redirect URL to an allow list in order for users to continue connecting to your app on Zapier. To access the new redirect URL, head to Step 2 of the Auth setup in the visual builder once the integration is public.

Add PKCE Support

Zapier provides built-in support for PKCE (Proof Key for Code Exchange and pronounced “pick-see”), an extension to the authorization code flow that adds a layer of protection against security vulnerabilities. The code generation and exchange steps of the flow occur automatically by Zapier when enabled.

Add Application Credentials to Zapier

In your application’s settings, you’ll receive credentials that Zapier will use to verify itself to your app—typically called a Client ID and Client Secret, though they may have a slightly different name. Copy that data from your app, then in Step 3 of your Zapier OAuth configuration, paste those items in their respective fields. Zapier will use that data along with the authorization URL to receive the request token.

Click Save & Continue to save your progress so far.

Zapier will automatically include the Client ID and Secret in authentication API calls, but if you need to reference them in your Zapier API calls or custom code, use the following codes:

• Client Secret: {{process.env.CLIENT_SECRET}}
• Client ID: {{process.env.CLIENT_ID}}

Add OAuth Endpoint Configuration

Now it’s time to configure how Zapier sends users to your API to allow access to their account in your app, and how Zapier gets the credentials it needs for future API calls.

First, add your application’s Authorization URL, where Zapier will redirect users to authenticate with your app. You can typically copy this URL from your application or integration settings where you copied the client ID and secret previously, or from your app’s API page. Typically, enter the URL in the field and leave the default settings.

By default, Zapier will pass the client ID, state, redirect URI, and a standard code response type as params in the request to the authorization url. If you need to change that, click the Show Options button and add any additional call details needed.

Note: The Oauth2 state param is a standard security feature that helps ensure that authorization requests are only coming from your servers. Most Oauth clients have support for this and will send back the state query param that the user brings to your app. The Zapier Platform performs this check and this required field cannot be disabled. The state parameter is automatically generated by Zapier in the background, and can be accessed at bundle.inputData.state. Since Zapier uses the state to verify that GET requests to your redirect URL truly come from your app, it needs to be generated by Zapier so that it can be validated later (once the user confirms that they’d like to grant Zapier permission to access their account in your app).

Optionally, if you wish to limit Zapier’s scope to let it only access specific data from your app, you can add OAuth scopes in the following field with a comma- or space-separated list.

Add Access Token Request and Refresh Token Request URLs

Next, add your app’s Access Token Request URL, typically with a POST call and the default settings Zapier uses if your app uses a standard OAuth configuration. You can find this URL in your application’s API documentation.

By default, Zapier will pass the client ID, client secret, authorization code, redirect URI, and a standard authorization_code grant type in the API request body. If you need to change that, click the Show Options button and add any additional call details needed.

If your API supports automated token refresh, add your API’s Refresh Token Request in the following field, and check the Automatically Refresh Token box. This will help Zapier stay connected to your users’ accounts and enable Zaps to run in the background without interrupting users as long as possible.

If your Access Token and Refresh Token requests don’t return the tokens at the top level, use Code Mode to modify the response so that the tokens are available at the top level. It’s not possible to store an object with nested keys from the response.

Zapier will automatically include the access token in subsequent API requests, but if you need to manually add it, the access token is stored in the authData bundle and can be referenced with {{bundle.authData.access_token}} or {{bundle.authData.accessToken}}, depending on how your API’s response references the access token.

Add a Test API Call

Zapier then needs a Test API call—typically to a /user or /me endpoint that returns details about the user and needs no additional configuration—to test account authentication and ensure the access token works.

Zapier will pass the access token with the API call by default, as it will with all subsequent API calls, but if your API requires any additional configuration, click the Show Options button and add any options needed for a successful API call.

If you need a specialized API call or response parsing on this or other API call steps, click Switch to Code Mode. The first time you click this, Zapier will convert the data in the form to JavaScript code that you can customize or replace. See How does Code Mode work? for more details.

Add a Connection Label

Finally add a connection label to help users identify each account that they add from your app to Zapier. Zapier includes your app’s name in the connection label by default, followed by the version number, then any text you include in the connection label. You can include:

• Plain text that will be included in every account connection
• Any input field from your authentication form (if present)
• Output fields from your app’s authentication test API call

Fields can be referenced using double curly braces. For example, a username field would look like {{username}}.

Learn more in our Connection Label documentation.

Click Save & Continue when finished to save your authentication settings.

Then, test your authentication, adding a real account to ensure Zapier can successfully connect to your app and use your test API call. Check our Authentication Testing docs for more details, common errors you may encounter, and how to resolve those.