Build Your Integration

Handle Authentication

Many Zapier integrations use OAuth v2 authentication to connect user accounts, including Zapier’s built-in GitHub integration

The first thing to set up is authentication. Your integration defines how Zapier’s platform authenticates with the API and what data needs to be collected from users to allow access to their accounts. Zapier supports most popular authentication schemes, including basic auth with username and password, API key auth, digest, session, and OAuth v2.

Whenever someone uses your integration in a Zap, they’ll first select your app, then will connect their account. That’s where the authentication flow comes in. Zapier shows a popup window where users login and select their account with OAuth2, or where they can enter account details with basic auth.

1. Select Your Authentication Scheme

Zapier supports a wide range of authentication schemes—select the best one for your app

We’ll use OAuth v2 in this example GitHub integration, following the steps here. With OAuth2, Zapier sends users to your site to authenticate. Click the Authentication tab in Zapier Visual Builder, then select OAuth v2 from the menu. Zapier will create a form to complete the required configuration automatically.

If you want to use another authentication scheme, check our auth docs for more details and use them instead of the steps below.

2. Configure Authentication Fields

If your OAuth v2 implementation is standard and users don’t need to input any additional fields such as sub domain to access the authorization url, you don’t need to make any changes in this section

If you do add input fields in this section, this will show a form to users with the fields you’ve added before redirecting them to your authorization URL. More on adding an OAuth v2 input form here. For our example GitHub integration, we will not make any changes to this section.

2. OAuth Redirect URL

Copy the OAuth Redirect URL generated by Zapier, and add it to the allowed list for the new application you’ve added for the OAuth integration with Zapier - typically this application is created in your app’s application, integration, or API settings. In GitHub’s interface, this field is called the authorization callback URL.

3. Enter Application Credentials

In your new application’s developer settings in GitHub, you’ll receive credentials that Zapier will use to verify itself to your app - called a Client ID and Client Secret.

Copy that data and paste those items in their respective fields. Zapier will use that data along with the authorization URL to receive the request token from GitHub.

Click Save & Continue to save your progress so far.

4. Add OAuth v2 Endpoint Configuration

Authorization URL

Add the Authorization URL https://github.com/login/oauth/authorize from GitHub’s documentation with the specified GET method.

Selecting Show Options allows you to further specify URL parameters and HTTP headers as needed for the authorization request. By default, Zapier includes client_id, state, redirect_uri and response_type as URL parameters, which you can edit as needed based on your API’s documentation.

For GitHub, we’ll keep the default settings.

Scope

An app’s API documentation will include the available scopes. For this example, we’ll give our app repo and user scopes. You can see all the available scopes for GitHub here.

Access Token Request

Next add the Access Token Request URL https://github.com/login/oauth/access_token as a POST call.

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.

Refresh Token Request

If your API supports automated token refresh, you would add your API’s Refresh Token Request endpoint here, and check the Automatically Refresh Token box to automatically request a refreshed token if any request receives a 401 from your app. 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.

For this example for GitHub, we’ll leave this section blank as reviewing the API docs, there is no mention of automated token refresh.

Test

Add an endpoint URL to test the user’s credentials and return a successful authentication message. Here we’ll add GitHub’s user API call https://api.github.com/user to the Test field.

Connection Label

Add a connection label, and users’ accounts in Zapier will be personalized to easily distinguish between multiple accounts.

You can also add details to the account. Whenever a new account is authenticated with Zapier, Zapier adds a Connection Label so users can identify accounts and add multiple accounts if desired. Customize this label with output fields from the API call (learn more in our connection label docs).

For GitHub, add {{bundle.inputData.login}} to the Connection Label to include the user’s GitHub username along with the app name that Zapier automatically includes.

5. Test The Authentication

OAuth v2 sends users from Zapier to your site to authenticate

Then test the authentication. Click Sign in, and authorize. If you’re already logged in, the OAuth window will briefly appear and authenticate the app. You can now use this GitHub account to test triggers and actions as you build them into your integration.

When others use your integration, they’ll see a similar login flow to connect their GitHub account to Zapier—only there, the popup window will open from the Zap Editor.