Authentication — Session Auth

Session authentication shares elements of Basic authentication—where Zapier requests users’ username and password then uses them to authenticate each API call—and OAuth v2—where Zapier redirects users to the app’s site to allow access then exchanges credentials for a token it uses to authenticate subsequent API calls. Session auth replies on a token, but has Zapier gather username, password, and other login details to use in an API call that then sends the auth token to Zapier. It works much like cookie-based authentication in your browser, only here the cookie is an auth token stored by Zapier.

Example Zapier session login form

When a user adds an app account to Zapier with Session auth, they first fill out an input form with any authentication credentials that app’s API requires. Zapier then sends a request to the API’s token exchange endpoint with those credentials, and the API responds with an authentication token. Zapier stores that authentication token and uses it with every subsequent API call.

When to use Session authentication: Use Session authentication with your Zapier integration if your API is designed for session, cookie, or token-based authentication. You can also use Session auth if your API uses a variant of OAuth that does not include an OAuth Authorization URL where users would otherwise login to your app and approve access to their accounts.

How to Add Session Auth to a Zapier Integration

Add Session Auth to Zapier integration

To add Session Auth to a Zapier integration, open your app’s Authentication page in Zapier visual builder then select Session Auth in the drop-down.

You will then need the following to set up Session Auth:

  • An input form, built inside Zapier, with fields for each data item your API needs for authentication
  • A Token Exchange Endpoint URL, where Zapier will send user credentials from the input form to your API and receive an auth token in the response
  • A Test API endpoint that Zapier can call to ensure the auth token works and allows access to the users’ account
  • A Connection Label to uniquely identify users’ accounts

Add a Session Auth Input Form

The first thing to add for Session auth is an input form. Much like Zapier’s input designer for triggers and actions, this lets you design a simple form for users to enter their username, password, API key, domain, or any other data your API requires for authentication.

In Step 1’s Configure your Fields section, click Add Fields to add a new field to your input form. There, add the following details:

  • 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.
  • 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
  • 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
  • Default Value: If your API request can accept standard data that works for every user, you can add a default value. Zapier will store and use the value on all API calls if set as non-required; if in a required field, Zapier will only use this value during account creation.

Be sure to add one fields for every piece of data users need to enter to authenticate their account with your API, as by default with Session auth, Zapier does not include any input fields.

If you need to use data received from the auth API response—such as team account names, domains, or subdomains—you can also optionall add a Computed Field. Add the field key, using the same field name as your API’s response—and leave the remaining fields blank, and 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 inlcuded in the response data. Learn more in our Computed Fields docs.

Save each field after adding it, then click Continue when every field your API needs has been added.

Add an Token Exchange Request

Zapier Session token exchange

Zapier then needs to exchange the credentials users enter in your input form for a session or access token. Zapier will pass the credentials to your API with this API call, then in subsequent API calls will use the token to authenticate the user.

Add the token exchange request URL in the field, select the correct HTTP call, and Zapier will automatically include the data from the input field in the API request body. If your API expects the data in the URL params or HTTP headers instead or requires additional data, click the Show Options and add the details your API call needs. Optionally, click the Switch to Code Mode toggle to write custom JavaScript code for the API call instead of using the form inputs.

Click Save & Continue once finished to store your API call settings.

Add a Test API Call

Session auth test API request

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 your users’ account authentication and ensure the access token works successfully.

Add the endpoint URL to the Test field, setting the correct HTTP call. Click Show Options to customize the API call if needed. Alternately, click the Switch to Code Mode toggle to replace the form data with custom JavaScript code for your API call and to parse the response bundle.

As Session Auth doesn’t include a defined standard for how access tokens are referenced in the response API and included in subsequent API calls, Zapier doesn’t include the access token by default. Add it yourself—here, and in subsequent Trigger and Action step API calls—in your API call settings. Click Show Options, then add the access token to your API call’s URL Params or HTTP Headers as needed. The Access Token will be in the bundle.authData, and typically be referenced as {{bundle.authData.access_token}}, {{bundle.authData.sessionToken}}, or a similar field depending on what how your API response lists the token.

Add a Connection Label

Example Session auth connection label

Finally add a connection label to uniquely identify each account users 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, or from your Token Exchange API call—enter {{bundle.authData.field}}, replacing field with the input form field key or Token Exchange API call field
  • Output fields from your app’s authentication test API call, referenced with {{bundle.inputData.field}} variables, replacing field for your API output field name

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, exchange user credentials for an access or session token, and use your test API call. Check our Authentication Testing docs for more details, common errors you may encounter, and how to resolve those.

Have any feedback or questions? Let us know.