Authentication#

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:

Auth

  • 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 authentication test 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; responding with status code 401 and no body is not helpful, while a body that reads Your API Key does not appear to be valid is. If you can have the API return a helpful message, then use scripting in Zapier to throw custom errors for specific status codes.

Connection Label#

You can set a Connection Label in your integration's Authentication settings to help customers remember which account they connected in each of their Connected Accounts. ​Easily identifiable values such as account name, email address, and name work great, but do not use private data including API keys, secrets, or tokens as Connection Labels.

Zapier always includes the app's name and integration version first, followed by any additional data you add to connection labels.

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), 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 input fields users fill out when adding authentication, including the username from basic auth and any custom fields added with other auth schemes.

As an example, Gmail uses the users' email address in the connection label, as Gmail's authentication test call returns an object with the email address. If you connected a Gmail account for contact@zapier.com, say, you'd see the account titled "Gmail contact@zapier.com" by default.

Gmail example connection labels

Set A Connection Label#

Zapier Platform UI Apps#

Connection Label

In Zapier Platform UI, add a connection label after adding your test API call. You can customize the label with data from the authData bundle with fields users entered while authenticating their account, or the inputData bundle with fields returned by the test API call. For example, add {{connectionLabel: ''}} to include a username field entered with Basic Auth or other authentication schemes where users enter their username.

Optionally, you can customize the connection label with JavaScript code.

Learn more in Zapier Platform UI's connection label docs.

Zapier Platform CLI Apps#

In Zapier Platform CLI, connectionLabel is part of the auth bundle. In your authentication settings, include a line such as {{connectionLabel: ''}} to include a username field that users entered when connection their account.

See additional examples in Zapier Platform CLI docs.

Legacy Web Builder Apps#

In Legacy Web Builder integrations, 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.

↑ Was this documentation useful? Yes No
Get Help