Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.zapier.com/llms.txt

Use this file to discover all available pages before exploring further.

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, calling /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. Best practice would include implementing the suggested fallback.

​
Directing the user to create a new Authentication

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

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.
2

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.
3

From the message, retrieve the new `authentication_id`

Afterwards, use that authentication_id to continue the workflow.
// 1. 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;
}

// 3. Wait for either the `postMessage` from `/partner/popup-close` or the user
// manually closing the popup. Then, use `new_authentication_id` to continue the
// Zap creation process. The `new_authentication_id` is the id of the authentication
// that the user just created.
//
// If falsy, we could not send postMessage for the reasons noted above, and you
// should call v2/authentications again instead.
const new_authentication_id = await new Promise((resolve) => {
  function onMessage(event) {
    if (event.origin === "https://zapier.com") {
      const action = event.data;
      if (action?.type === "zapier.popup.close") {
        authPopup.close();
        finishAndCleanUp(action.authentication_id);
      }
    }
  }

  function finishAndCleanUp(authentication_id) {
    resolve(authentication_id);
    removeEventListener("message", onMessage);
    clearInterval(interval);
  }

  // 2. Add an event listener to be alerted when the user has completed the auth flow.
  addEventListener("message", onMessage);

  // 2. Or, wait for popup to be closed if the message wasn't received
  const interval = setInterval(() => {
    if (authPopup.closed) {
      finishAndCleanUp();
    }
  });
});
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 Zaps 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": {}
  }
}