Selecting an Authentication

An Authentication is a set of user credentials for an App that is stored securely by Zapier. When required, a user must select which of the Authentications they have for that App (they may have multiple) that they would like to use when an Action executes.

Authentication Schema

We can fetch a list of Authentications available for an App by making a request to the /authentications endpoint:

// GET /authentications?app=4b3920d6-1d5a-4071-b837-9383dc511b80
{
  "data": [
    {
      "type": "authentication",
      "id": "49509",
      "app": "4b3920d6-1d5a-4071-b837-9383dc511b80",
      "title": "SuperExampleCRM (wade@zapier.com)",
      "is_expired": false
    },
    {
      "type": "authentication",
      "id": "96983",
      "app": "4b3920d6-1d5a-4071-b837-9383dc511b80",
      "title": "SuperExampleCRM (bryan@zapier.com)",
      "is_expired": false
    }
  ]
}

Our user can then select one of these Authentications to use with an Action.

When no Authentications exist

It’s possible that the user doesn’t have any Authentications for an App they’ve picked, as in every case when it’s a new Zapier account. In these cases the /authentications endpoint will return an empty list under the data key. In this scenario, we should direct the user to the url provided by the /apps endpoint under the links.connect_new_authentication key to add a new Authentication. This is also the best approach to take if you want to offer the user the option to use a new Authentication with this Action, even if they already have Authentications available. (e.g. If the user wants to use a different SuperExampleCRM account than the ones already linked to Zapier).

If links.connect_new_authentication is null, then this app doesn’t require authentication, and null should be passed instead of a valid id. Read more about that below.

Because postMessage requires a handler to send the message to, any portion of the flow that breaks window.opener for Zapier will result in no message being sent. In such cases, polling the /authentications endpoint is the best option to retrieve the new authentication ID. Zapier cannot override third-party flows to force an opener to be persisted, and third-party code may change at any time. The code sample below implements this fallback: do not rely on postMessage alone.

Directing the user to create a new Authentication

The best way to use this links.connect_new_authentication link is as follows:

Snapshot the user's existing authentications for the app

Before opening the popup, call the /authentications endpoint and record the IDs already returned. The fallback in a later step uses this snapshot to detect the new authentication once it is created.

Open the `links.connect_new_authentication` link in a popup

In this popup, the user will be prompted to authenticate with the app, and to allow Zapier to access that app.

Create an event listener to listen for `zapier.popup.close` messages from that popup

A message with that type will be posted when the auth flow in the popup is complete. Treat this as the fast path: it does not fire if the popup loses its window.opener reference, which some third-party auth flows do.

Poll `/authentications` as a fallback while the popup is open

Some third-party sites sever window.opener during their own redirect chain, so the postMessage in the previous step never arrives. Poll the same /authentications endpoint on an interval and resolve as soon as an authentication ID appears that was not in the snapshot from step 1. This path never depends on window.opener, so it works even when postMessage cannot be delivered.

From either path, retrieve the new `authentication_id`

Afterwards, use that authentication_id to continue the workflow. The full implementation below combines all of these steps, plus a dismissal check on popup.closed and an absolute timeout so an abandoned popup cannot hang the flow forever.

// `fetchAuthentications` should call GET /authentications?app=<id> and
// return the `data` array from the response.
async function connectNewAuthentication(
  app,
  { fetchAuthentications, pollIntervalMs = 2000, pollTimeoutMs = 5 * 60 * 1000 } = {},
) {
  if (!app.links.connect_new_authentication) return null;

  // 1. Snapshot existing authentications before opening the popup, so the
  // fallback can detect "a new one appeared" on its own, with no message
  // from the popup required.
  const before = new Set((await fetchAuthentications()).map((a) => a.id));

  // 2. Open a popup window to the `links.connect_new_authentication` url.
  const authPopup = window.open(
    app.links.connect_new_authentication,
    "_blank",
    "width=1280,height=1024",
  );
  if (!authPopup) {
    alert("Please allow popups to continue.");
    return;
  }

  return new Promise((resolve) => {
    let settled = false;

    function cleanup() {
      settled = true;
      removeEventListener("message", onMessage);
      clearInterval(closedPoll);
      clearInterval(authPoll);
      clearTimeout(giveUpTimer);
      try {
        authPopup.close();
      } catch {
        // Ignore: the popup may already be closed, or `window.opener` may
        // have been severed by the third-party flow.
      }
    }

    // 3. Fast path: resolve as soon as the popup posts a `zapier.popup.close`
    // message with the new authentication_id.
    function onMessage(event) {
      if (settled || event.origin !== "https://zapier.com") return;
      const action = event.data;
      if (action?.type === "zapier.popup.close") {
        cleanup();
        resolve(action.authentication_id);
      }
    }
    addEventListener("message", onMessage);

    // Dismissal signal: if the user closes the popup without completing
    // auth, give the fallback poll a couple more cycles, then resolve with
    // no authentication.
    const closedPoll = setInterval(() => {
      if (settled) return;
      try {
        if (authPopup.closed) {
          clearInterval(closedPoll);
          setTimeout(() => {
            if (!settled) {
              cleanup();
              resolve(undefined);
            }
          }, pollIntervalMs * 2);
        }
      } catch {
        // `authPopup.closed` can throw if `window.opener` was severed.
        // The authentications poll below is the fallback for this case.
        clearInterval(closedPoll);
      }
    }, 500);

    // 4. Fallback path: poll `/authentications` for an ID that was not in
    // the snapshot from step 1. This never touches `window.opener`, so it
    // works even when `postMessage` cannot be delivered.
    const authPoll = setInterval(async () => {
      if (settled) return;
      try {
        const current = await fetchAuthentications();
        const created = current.find((a) => !before.has(a.id));
        if (created) {
          cleanup();
          resolve(created.id);
        }
      } catch {
        // Ignore transient fetch errors; the next tick tries again.
      }
    }, pollIntervalMs);

    // Absolute timeout so an abandoned popup cannot hang the flow forever.
    const giveUpTimer = setTimeout(() => {
      if (!settled) {
        cleanup();
        resolve(undefined);
      }
    }, pollTimeoutMs);
  });
}

Looking to add an authentication to your own app? You can supply auth details directly and streamline the process. Check out Adding App Authentications.

When Authentication is not required

Some apps don’t require authentication at all - like Webhooks. You’ll know this is the case when fetching the app and it’s not possible to add a new authentication.

Sample response from /apps

...
"links": {
          "connect_new_authentication": null
        },
...

When creating Zap workflows or running Actions with these apps, null should be passed in place of a valid authentication id;

// POST https://api.zapier.com/v2/actions/core:8yjfgwyq03zskh3LOe9jPa5dOeW/inputs
{
  "data": {
    "authentication": null,
    "inputs": {}
  }
}

// POST https://api.zapier.com/v2/zaps
...
"steps": [
      ...
      {
        "action": "core:3ZYFzZKkjbDK2AwQopVqrZWL9pK",
        "inputs": {
          "url": "https://greatWebhooks.com/myWebhook"
        },
        "authentication": null
      }
    ]
...

Powered By Zapier

API Authentication

Embedding Zapier

Zap Creation

Running Actions

Sponsor User Automation

Managing App Authentications

Zap Templates

AI Workflows

API Specification

Selecting an Authentication

When no Authentications exist

Directing the user to create a new Authentication

When Authentication is not required

​When no Authentications exist

​Directing the user to create a new Authentication

​When Authentication is not required

When no Authentications exist

Directing the user to create a new Authentication

When Authentication is not required