You are configuring your Contact Form 7 form to send data to an external API. You open the plugin's authentication settings and see three options: Basic Auth, API Key, and Bearer Token.
Which one do you choose?
The answer depends entirely on what the target API expects. Using the wrong method is one of the most common causes of 401 errors, and it is entirely preventable. This guide explains each method, when to use it, and how to configure it correctly.
The Three Authentication Methods at a Glance
| Method | How It Works | Security Level | Best For |
|---|---|---|---|
| Basic Auth | Username and password encoded in Base64 | Low | Legacy systems, simple integrations, testing |
| API Key | A static key passed in a header or query parameter | Medium | Internal APIs, simple token-based auth |
| Bearer Token | A token (often JWT) passed in the Authorization header | Medium-High | Modern APIs, OAuth 2.0 flows, expiring tokens |
Basic Auth: Simple but Limited
Basic Auth is the oldest and simplest authentication method. You send a username and password with every request, encoded in Base64.
How it works:
The credentials are combined as username:password and encoded. The request header looks like this:
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
When to use it:
Basic Auth is appropriate for legacy systems that were built before modern authentication standards existed. It is also useful for quick testing and debugging because it requires no token generation or refresh logic.
When to avoid it:
Basic Auth is not inherently secure. The Base64 encoding is not encryption. Anyone who intercepts the request can decode the credentials in seconds. For production integrations, especially those handling sensitive customer data, a more secure method is strongly recommended.
Common use case in CF7 integrations:
Zendesk uses Basic Auth for its API. The username format is email/token, and the password is your API token. This is a case where Basic Auth is the required method, not a choice. For a full walkthrough of Zendesk authentication, see this guide on Contact Form 7 API authentication errors.
API Key: Simple and Static
An API Key is a static token that identifies your application or account. Unlike Bearer tokens, API keys typically do not expire. You generate them once and use them indefinitely.
How it works:
The key can be passed in several ways, depending on the API. Common locations include:
-
Authorization header:
Authorization: YOUR_API_KEY -
Custom header:
X-API-Key: your-key-here -
Query parameter:
?api_key=your-key-here
The plugin supports custom header configuration, so you can place the API key wherever the target API expects it.
When to use it:
API Keys are common for internal APIs, simple integrations, and services where the key identifies the application rather than a specific user. HubSpot private apps, for example, use an access token that functions like an API key.
Security considerations:
API keys provide authorization but not authentication. This means the key grants access to resources, but it does not verify who is making the request. If the key is intercepted, anyone can use it. Store API keys in environment variables or secure configuration, never in version control.
Bearer Token: Modern and Expiring
Bearer Token authentication is the most common method for modern APIs. The token is typically a JSON Web Token (JWT) or an OAuth 2.0 access token.
How it works:
You first obtain a token from the API's authentication endpoint. Then you include that token in the Authorization header:
Authorization: Bearer your-token-here
The word "Bearer" means that whoever holds the token can use it. The token itself is a cryptic string that proves your identity.
When to use it:
Bearer Tokens are the standard for OAuth 2.0 flows. If the API documentation mentions OAuth, access tokens, or token expiration, you need Bearer Token authentication. This is common with enterprise platforms like Salesforce, Google Workspace, and Microsoft 365.
Token expiration:
Unlike API keys, Bearer tokens expire. HubSpot access tokens, for example, expire after 30 minutes (1800 seconds). When a token expires, you need to refresh it using a refresh token.
This is where the plugin's OAuth add-on becomes valuable. The free version does not support automatic token renewal. The PRO add-on handles this automatically, refreshing tokens in the background so your integrations continue running without interruption.
Common use case in CF7 integrations:
HubSpot private apps use Bearer Token authentication. You generate a token in HubSpot's private app settings and paste it into the plugin's Bearer Token field. The Community forum confirms this is the standard approach for HubSpot integrations.
How to Choose: A Decision Framework
Step 1: Check the API documentation.
This is non-negotiable. The API documentation tells you exactly which authentication method it requires. Look for sections labeled "Authentication," "Authorization," or "API Keys."
Step 2: Match the method to the API's requirements.
| API Says | Use This Method |
|---|---|
| "Basic Auth" or "username/password" | Basic Auth |
| "API Key" or "X-API-Key" | API Key |
| "Bearer Token" or "OAuth 2.0" | Bearer Token |
| "JWT" or "access token" | Bearer Token |
Step 3: Consider the security requirements.
If the API supports multiple methods, choose the most secure one. Bearer Tokens with expiration are generally more secure than static API keys, which are more secure than Basic Auth.
Step 4: Test with the simplest method first.
If you are debugging a connection issue, start with Basic Auth or API Key. These are easier to configure and have fewer moving parts. Once the connection works, switch to the more secure method if needed.
Configuring Authentication in the Plugin
The plugin provides header input fields where you configure authentication manually.
For Basic Auth:
You need to Base64-encode your credentials before pasting them into the header field. The plugin does not execute PHP code in the header textarea, so you must encode the string externally.
For API Key:
Add a custom header with the API key. The exact header name depends on the API. Some use Authorization, others use X-API-Key, and some use api-key.
For Bearer Token:
Add the Authorization header with the value Bearer your-token-here. If your token expires, you will need to update it manually unless you use the PRO add-on with automatic token refresh.
Common Mistakes to Avoid
Using Bearer Token for an API that expects Basic Auth.
This is the most common 401 error cause. If the API documentation says "Basic Auth" and you send Authorization: Bearer, the request will be rejected.
Forgetting the "Bearer" prefix.
The header value must be Bearer token-here, not just token-here. The prefix tells the API how to interpret the token.
Using an expired token.
Bearer tokens expire. If your integration suddenly stops working after previously working fine, the token may have expired. Check the token's expiration settings in the API's dashboard.
Hardcoding credentials in the header without encoding.
For Basic Auth, the credentials must be Base64 encoded. Sending plain username:password will fail.
For a deeper dive into JSON structure mapping and header configuration, read this guide on Contact Form 7 JSON mapping.
Beyond Authentication: One Form, Multiple Destinations
Once your authentication is configured correctly, you might want to send the same form submission to multiple tools: a CRM, an email marketing platform, or a help desk system.
A good connector plugin supports multiple API integrations from a single form submission. You can create a CRM contact, send an SMS via Twilio, and create a Zendesk ticket, all from one CF7 submission, without Zapier. For a cost comparison, see this article on Zapier vs a dedicated API plugin.
Key Takeaways
Check the API documentation first. The API tells you which method it requires. Guessing leads to 401 errors.
Basic Auth is for legacy systems and testing. It is simple but not secure. Use it when the API requires it, not by choice.
API Keys are for static integrations. They do not expire, which is convenient but less secure. Store them carefully.
Bearer Tokens are for modern APIs. They expire, which is more secure but requires refresh logic. The PRO add-on handles this automatically.
Match the header format exactly. Bearer, Basic, and custom prefixes are not interchangeable. One wrong character means a failed request.
With the right authentication method, correct header formatting, and an understanding of token lifecycle, your CF7 form will connect to any API reliably.
Top comments (0)