When you connect an API to your AI Agent through Actions, you handle sensitive customer data and authentication keys.
Scopes & Least-Privilege Keys
Always apply the principle of least privilege — give your API keys access only to what your Action needs.
Developer guidelines
-
Create dedicated API credentials for the AI Agent.
Don’t reuse admin or personal tokens.
-
Limit scopes to the minimal endpoints required.
Example: read-only access for “order lookup” Actions.
-
Avoid wildcard or full-access scopes (*).
-
Rotate API keys periodically (e.g., every 90 days) and revoke unused ones.
Store keys only inside Watermelon’s authentication fields — never hard-code them in schemas or Domain Knowledge.
Handling Personal Data (PII)
Actions often exchange personal data such as names, emails, or postal codes. Handle all PII as confidential.
| Guideline | Implementation Tip |
|---|
| Minimize | Only request attributes required by the API (e.g. email, not full address). |
| Mask where possible | Avoid returning full PII in responses; display partial data like j***@example.com. |
| Don’t log secrets | The Interactive Tester hides tokens, but avoid echoing them in Domain Knowledge or responses. |
| Use test data | When validating or demonstrating Actions, use anonymized examples. |
Sensitive info (passwords, credit-card numbers, tokens) should never pass through chat inputs.
HTTPS Only & Allow-Listing Base URLs
Watermelon requires HTTPS for all external API calls to ensure encrypted traffic.
Checklist
-
Confirm every server in your schema uses https://, not http://.
-
Allow-list known, trusted base URLs in your backend or firewall.
This prevents the AI Agent from sending data to unverified hosts.
-
Avoid temporary or test URLs unless absolutely required.
Example:
servers:
- url: "https://api.example.com/v1"
description: "Production"
Avoid Dangerous Endpoints (Write/Delete Operations)
Limit Actions to read or safe write endpoints.
| Risky Endpoint | Safer Alternative |
|---|
| DELETE /users/id | Skip or protect with manual approval |
| PATCH /orders/id/status | Restrict to specific statuses |
| POST /admin/config | Don’t expose admin controls to AI Agent |
- Require clear user confirmation in Domain Knowledge.
- Protect it with authentication and idempotency keys.
- Log requests securely (see below).
Data Storage & Retention in Watermelon
Watermelon temporarily processes Action data to complete a conversation.
To stay GDPR-compliant:
- Conversation data is stored in Watermelon’s secure EU infrastructure.
- API responses are not permanently stored; they are cached only for the session.
- Logs of failed calls and schema metadata are kept for debugging but contain no customer PII.
- To remove historical logs or messages, use the account-level data-deletion request feature.
If your organization has its own retention policy, align your Action setup accordingly — e.g., mask data earlier or shorten retention.
