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 a Zap executes.

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 a Zap.

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 Zap, 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.

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 Zap creation process

// 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;
}

// 2. Add an event listener to be alerted when the user has completed the auth flow.
window.addEventListener('message', function(event) {
  if (event.origin === 'https://zapier.com') {
    const action = event.data;
    if (action?.type === "zapier.popup.close") {
      if (authPopup) {  // In case popup has already been closed
        authPopup.close();
      }
      const new_authentication_id = action.authentication_id;
      // 3. 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.
    }
  }
});
Looking to add an authentication to your own app? You can supply auth details directly and streamline the process. Check out Adding an Authentication.

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 with these apps, null should be passed in place of a valid authentication id;