OAuth v2 authentication matches in appearance the login process users expect from most modern apps.
The user interaction with authenticating Zapier typically takes place in full on the app’s own site, helping users easily connect accounts without needing to share account credentials or look up API keys.
The user will see a familar window from your app showing either a login screen or if they’re already logged in, an account selector where they don’t need to enter credentials. Once they authorize Zapier access, the app will return an access token that Zapier uses in future API calls.
Zapier implements the “Authorization Code” grant type when you choose OAuth v2 in the Platform UI. If your OAuth v2 implementation supports refresh tokens, you can optionally configure a “Refresh Token” request.
Platform UI does not currently support other grant types. If your integration requires a different OAuth v2 grant type, you’ll need to use another supported authorization type with Zapier such as Session or API Key.
If your integration requires OAuth v1 authentication, use the Platform CLI instead of Platform UI.
Most apps with OAuth v2 authentication do not need an input form. If your API requires data from the user before displaying the authorization URL, or requires URL details to create the authorization URL; such as account team name or site URL for self-hosted apps, or you need to store fields received from your server to use in subsequent API calls - you’ll need an input form.
Add those additional fields by selecting Add Fields and fill in the details for any field requiring user input. This will show a form to users with the fields you’ve added before redirecting them to your authorization URL.
Two types of fields are available when building an OAuth v2 input form. Standard Fields, work much like other form fields with Zapier’s input form in triggers and actions. Computed Fields make sure specific fields are returned by your app’s authentication API call response.
For standard fields to be input by the user, select the default Field type. Add the most commonly needed fields first, in the order users expect, as you cannot reorder fields once added. Fill in the options as appropriate:
– 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: All input fields use the string
text field by default; select password
instead if you would like to obscure the data as users enter it.
– Help Text: Include details to assist users in authenticating with your app, especially if they may be unsure where to find the data needed within your app. Format text with Markdown, and include a hyperlink if needed.
– 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: Include a value for this field to be used as a fallback. For optional fields, the default value is set on initial connection creation and used in the API call instead of missing or null values every time the Zap runs. For required fields, this value is used during connection creation, but not when the Zap runs (Zapier raises an error for missing/null values instead).
Input fields marked as password and all authentication fields with sensitive, private data such as both username and password from OAuth v2 are automatically censored at runtime. These values are stored in the Auth bundle and used in API calls, but are replaced in Zapier’s logs with a censored value like this :censored:6:82a3be9927:
. Due to this, it is not possible to view the exact tokens or keys in Zapier’s logs. To verify that the same token as was returned by the authentication, is being used in subsequent API calls; you can compare censored value characters, for example :censored:6:82a3be9927:
would have the same value ending in 9927 when used in a subsequent call.
Each input field is listed with its label, key, type, and required status in your authentication settings. Click the field to edit it, or click the gear icon and select Delete to remove a field.
{{bundle.inputData.redirect_uri}}
Click Save & Continue to save your progress so far.
Zapier automatically includes the Client ID and Secret in authentication API calls, but if you need to reference them in your integration’s API calls or custom code, use the following codes: – Client Secret: {{process.env.CLIENT_SECRET}}
– Client ID: {{process.env.CLIENT_ID}}
code
response type as URL 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 thestate
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 atbundle.inputData.state
. Since Zapier uses thestate
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).
To optionally limit Zapier’s scope to let it only access specific data from your app, add OAuth scopes in the Scope field with a comma- or space-separated list.
Add your app’s Access Token Request URL from your API documentation, typically with 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 with the access token request. 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 URL, and check the Automatically Refresh Token box. This enables users’ Zaps to run in the background without interruptions as long as possible by refreshing expired access tokens automatically.
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 is 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.
/user
or /me
call. Add the URL for the API call, and set the call type, typically a GET
. This will test the user-entered credentials to ensure it enables a successful API call to your app.Review connection label documentation to optionally differentiate the app accounts users connect.
Connect a valid user account to test authentication.
You can also refer to this video on implementing OAuth v2 in your Zapier integration:
Need help? Tell us about your problem and we’ll connect you with the right resource or contact support.
OAuth v2 authentication matches in appearance the login process users expect from most modern apps.
The user interaction with authenticating Zapier typically takes place in full on the app’s own site, helping users easily connect accounts without needing to share account credentials or look up API keys.
The user will see a familar window from your app showing either a login screen or if they’re already logged in, an account selector where they don’t need to enter credentials. Once they authorize Zapier access, the app will return an access token that Zapier uses in future API calls.
Zapier implements the “Authorization Code” grant type when you choose OAuth v2 in the Platform UI. If your OAuth v2 implementation supports refresh tokens, you can optionally configure a “Refresh Token” request.
Platform UI does not currently support other grant types. If your integration requires a different OAuth v2 grant type, you’ll need to use another supported authorization type with Zapier such as Session or API Key.
If your integration requires OAuth v1 authentication, use the Platform CLI instead of Platform UI.
Most apps with OAuth v2 authentication do not need an input form. If your API requires data from the user before displaying the authorization URL, or requires URL details to create the authorization URL; such as account team name or site URL for self-hosted apps, or you need to store fields received from your server to use in subsequent API calls - you’ll need an input form.
Add those additional fields by selecting Add Fields and fill in the details for any field requiring user input. This will show a form to users with the fields you’ve added before redirecting them to your authorization URL.
Two types of fields are available when building an OAuth v2 input form. Standard Fields, work much like other form fields with Zapier’s input form in triggers and actions. Computed Fields make sure specific fields are returned by your app’s authentication API call response.
For standard fields to be input by the user, select the default Field type. Add the most commonly needed fields first, in the order users expect, as you cannot reorder fields once added. Fill in the options as appropriate:
– 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: All input fields use the string
text field by default; select password
instead if you would like to obscure the data as users enter it.
– Help Text: Include details to assist users in authenticating with your app, especially if they may be unsure where to find the data needed within your app. Format text with Markdown, and include a hyperlink if needed.
– 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: Include a value for this field to be used as a fallback. For optional fields, the default value is set on initial connection creation and used in the API call instead of missing or null values every time the Zap runs. For required fields, this value is used during connection creation, but not when the Zap runs (Zapier raises an error for missing/null values instead).
Input fields marked as password and all authentication fields with sensitive, private data such as both username and password from OAuth v2 are automatically censored at runtime. These values are stored in the Auth bundle and used in API calls, but are replaced in Zapier’s logs with a censored value like this :censored:6:82a3be9927:
. Due to this, it is not possible to view the exact tokens or keys in Zapier’s logs. To verify that the same token as was returned by the authentication, is being used in subsequent API calls; you can compare censored value characters, for example :censored:6:82a3be9927:
would have the same value ending in 9927 when used in a subsequent call.
Each input field is listed with its label, key, type, and required status in your authentication settings. Click the field to edit it, or click the gear icon and select Delete to remove a field.
{{bundle.inputData.redirect_uri}}
Click Save & Continue to save your progress so far.
Zapier automatically includes the Client ID and Secret in authentication API calls, but if you need to reference them in your integration’s API calls or custom code, use the following codes: – Client Secret: {{process.env.CLIENT_SECRET}}
– Client ID: {{process.env.CLIENT_ID}}
code
response type as URL 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 thestate
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 atbundle.inputData.state
. Since Zapier uses thestate
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).
To optionally limit Zapier’s scope to let it only access specific data from your app, add OAuth scopes in the Scope field with a comma- or space-separated list.
Add your app’s Access Token Request URL from your API documentation, typically with 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 with the access token request. 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 URL, and check the Automatically Refresh Token box. This enables users’ Zaps to run in the background without interruptions as long as possible by refreshing expired access tokens automatically.
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 is 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.
/user
or /me
call. Add the URL for the API call, and set the call type, typically a GET
. This will test the user-entered credentials to ensure it enables a successful API call to your app.Review connection label documentation to optionally differentiate the app accounts users connect.
Connect a valid user account to test authentication.
You can also refer to this video on implementing OAuth v2 in your Zapier integration:
Need help? Tell us about your problem and we’ll connect you with the right resource or contact support.