Authentication — API Key Auth
API Key authentication lets apps verify users account with an API key that is passed along with every API call. In a Zapier integration using API Key authentication, Zapier includes the API key—optionally along with any other data your API needs—every time a Zap step runs.
Example API key auth screen for users inside Zapier
API Key authentication works similarly to Zapier’s Basic Auth in that Zapier passes the credentials with every API call. Here, though, you need to build the input form where users add their API key and any other optional information your API requires, such as their account name, site URL, and other identifying data. You can additionally include help text under each field to direct users to where they can retrieve their API key.
When to use API key authentiocation: Use API key authentication if your API primarily uses an API key to identify accounts, especially with apps for weather, maps, content verification, file conversion, and other data tools that require a key for access to the service but do not contain user-specific content. Alternately, since API key authentication allows you to create a custom input form, you can use it to customize username and password-based logins that don’t fit Zapier’s default Basic auth scheme.
How to Add API Key Auth to a Zapier Integration
To add API Key Auth to your Zapier integration, open the Authentication tab in Zapier visual builder and select API key.
You then need to:
- Build an input form for users to enter their API key and any other required data
- Add a test API call to verify user credentials when adding new accounts
- Add a connection label to identify each added account
- Test the authentication to ensure it works and to obtain a testing login that can be used in testing subsequent Zap steps as you add them
Add an API Key Input Form
Start by adding a form where users will enter their API key and other authentication details when connecting their app account to Zapier. Check your API documentation for what fields are required, including user or account names, domains, and more. Additionally, note any details users may need on how to find that data, since API keys especially are often hidden under settings menus and you’ll need to include those details in your input form’s help text.
For each field that you need, click the Add Fields button and fill in the details for your field. Be sure to add the most commonly needed fields first, in the order users expect, as you cannot reorder fields once added.
Every input field requires a Key, the name your API uses to reference this field. Enter the same key name that your API uses.
Then fill in the optional fields, as appropriate, especially the Label:
- Label: A human friendly name for this field. Enter what this value is called inside your app’s UI.
- Is this field required: Check this box for your API key field, and for any other fields that your API requires for authentication.
- Type: Zapier uses the
stringtext field for all input fields by default; select
passwordinstead if you would like to obscure the data as users enter it.
- Help Text: Include details to assist users in authenticating with your app, especially if they may be unsure where to find the data needed. Format text with Markdown, and include a link if needed.
- Default Value: Include a value for this field to be used a fallback. For optional fields, the default value is set on initial creation and used instead of missing or null values every time the Zap runs. For required fields, this value is used during Zap creation, but not when the Zap runs (Zapier raises an error for missing/null values instead).
Note: The input field designer also includes an option for computed fields; those are not applicable to API key login, and are only used with OAuth v2 and Session auth.
Once you’ve added your input fields, Zapier lists each input field with its label, key, type, and required status on your authentication settings. Click the field to edit it, or click the gear icon and select Delete to remove a field.
When you’ve added the needed forms, click Continue to add a test API call and continue setting up your app’s authentication.
Add a Test API Request
Zapier then needs a way to test the API key and other input field data users enter, and ensure it enables a successful API call. For that, in step two, add an API call to your API that requires no configuration, typically a
/me call. Add the URL for the API call, and set the call type.
Zapier automatically includes the API key and any additional input fields you added to your input form in the URL Params. If your API needs that data as headers instead, click Show Options and add the details there instead.
Configure a Connection Label
Finally add a connection label to help users identify each account that they add from your app to Zapier. Zapier includes your app’s name in the connection label by default, followed by the version number, then any text you include in the connection label. You can include:
- Plain text that will be included in every account connection
- Any input field from your authentication form—enter
fieldwith your input form field key
- Output fields from your app’s authentication test API call, referenced with
fieldfor your API output field name
Learn more in our Connection Label documentation.
Click Save & Continue when finished to save your authentication settings.
Then, test your authentication, adding a real account to ensure Zapier can successfully connect to your app and use your test API call. Check our Authentication Testing docs for more details, common errors you may encounter, and how to resolve those.