Before you start building your authentication flow, we recommend reviewing the guidelines in our Planning Guide.

Authentication Configuration#

  • If you use API Keys, provide adequate help text so that the user can easily connect their account to Zapier. A direct URL (or as direct as possible) should be provided in the help text to get the person to their API key. The API key should be information that your users can find in their own account with enough instructions and not information that is only accessible by reaching out to your support team.

  • You can write the help text in Markdown so that the link is embedded into the description:


  • If you use subdomains, use our “subdomain” auth field type so the user doesn’t have to guess what formatting you expect for the domain or interpret from help text. If you need a full domain, use scripting to ensure the small details are correct (like https:// or a trailing slash on the URL) for the user.

Authentication Testing#

  • Your test trigger should ping a dedicated endpoint to determine if an auth is valid or not. Many apps have an endpoint that is something like /me.json. This is perfect. If not, pick the resource that is most likely to return 2xx when a valid auth is set up. The last thing we want is a 4xx when a valid auth exists because there isn’t a resource at the test trigger endpoint.
  • If the authentication fails, return a message that tells the user what is invalid. For example "401 and said nothing" is bad, whereas "Your API Key does not appear to be valid" is better. This can be fixed by updating the response code delivered by the API or via scripting in Zapier.

Connection Label#

You can set a Connection Label in Authentication Settings to help your customers remember which account they connected in each of their Connected Accounts.

You can use data from either of two sources to define a Connection Label:

  1. Data returned in the result of the test trigger (which must be an object)
    • This option is especially useful if your test trigger calls a /me endpoint that returns information about the user such as their name or email address
  2. Any authentication fields
    • Note that apps using OAuth authentication don't have authentication fields so they would need to use the test trigger data

As an example, Gmail uses {{email}} (the test trigger returns an object with that email property), so when a customer connects a Gmail account for, they'll see it titled "Gmail" by default.

GMail example connection labels

Setting A Connection Label#

Web Builder Apps#

In Web Builder, click Manage Authentication Settings from your app development tab: Manage authentication settings

You’ll see an option to include the connection label: Connection Label

Accessing Nested Properties#

To access nested properties in the data returned by the test trigger, use a double underscore. For example, consider this example object returned by a test trigger:

  user: {
      name: "Arya Stark",
      id: 1234

To set the Connection Label to "Arya Stark", you would use {{user__name}}.

Alternatively, you can set the connection label in Scripting with the get_connection_label method.

CLI Apps#

In Zapier CLI, connectionLabel is part of the auth bundle.

↑ Was this documentation useful? Yes No
Get Help