Overview of Authentication Methods
| Method | Description | Security Level | When to Use |
|---|---|---|---|
| No Authentication | Open connection, no credentials required | Low | Public APIs or internal test environments |
| Basic Authentication | Username + password | Medium | Simple API connections (e.g., internal systems) |
| Bearer Authentication (API Key) | Token-based | High | Standard for most APIs |
| Custom Authentication | Custom headers or query parameters | High | APIs with non-standard token or signature systems |
No Authentication
This is the simplest option — and also the least secure.
What It Means
No credentials or keys are required. The API endpoint is publicly accessible, so anyone with the URL can send a request.How to Set It Up
- In your Watermelon Action, select No authentication.
- Leave all credential fields empty.
- Test your Action to confirm the connection works.
Basic Authentication
Basic Authentication uses a username and password to verify access.
How It Works
Each time your AI Agent sends a request, it includes an encoded string containing your username and password in the header. The API server checks these credentials before allowing access.How to Set It Up
- In your Watermelon Action, choose Basic Authentication.
- Enter your:
- Username
- Password
- Save the Action.
- Test the connection in the Interactive Tester.
Example
If the API documentation shows:API Key Authentication
Many APIs use a key or token instead of a username and password. In Watermelon, there are two types of API Key authentication:- Bearer Authentication (standard)
- Custom Authentication (flexible)
1. Bearer Authentication
Bearer tokens are the most common way to authenticate securely with APIs.
How It Works
You receive a token (API key) from the service provider. Each API call must include this token in the Authorization header like this:How to Set It Up
- In your Action setup:
- Choose Auth Type: Bearer.
- Paste your Token in the provided field.
- Save and test your Action.
Example
If your API documentation says:- Auth Type: Bearer
- Token: abc123xyz
Best for: APIs like HubSpot or other modern SaaS tools that use OAuth-style tokens.
2. Custom Authentication
Some APIs use unique authentication methods. Custom authentication lets you define exactly how credentials are sent. You can add extra details to either the Headers or Query Parameters.Option A — Add to Headers
Headers are used to send metadata about your request, such as authentication or session info.
- Choose Custom Authentication.
- Add key–value pairs under Headers.
- You can add up to 10 headers per request
Option B — Add to Query Parameters
Query parameters are added at the end of the URL, visible like this:
- Choose Custom Authentication.
- Add key–value pairs under Query Parameters.
- You can add up to 10 parameters per request.
Choosing the Right Method
| Situation | Recommended Method |
|---|---|
| Public endpoint, no login needed | No Authentication |
| Internal system with simple access | Basic Authentication |
| Modern SaaS API (e.g. HubSpot, Shopify) | Bearer Authentication |
| Custom or legacy API | Custom Authentication |
Troubleshooting Authentication
| Error Code | Meaning | What to Check |
|---|---|---|
| 401 Unauthorized | Invalid credentials or token | Verify your API key, username/password, or token format |
| 403 Forbidden | Access denied | Check if your API user has sufficient permissions |
| 404 Not Found | Wrong endpoint | Verify the URL or BaseURL |
| 500 Server Error | Server issue | Retry later or contact API provider |
| Invalid Auth Type | Wrong selection in Watermelon | Double-check the authentication method required by the API |
Security Best Practices
Use secure tokens (Bearer or Custom) whenever possible.
Limit API permissions to the minimum required scope.
Always use HTTPS for encrypted communication.
Rotate API keys periodically for added security.