Security
Keep credentials, webhooks and data inside their boundaries.
Polymorfa separates people signed in to the Console, server credentials and end-user client tokens. Each request is authorized against the current state of your team and project, so a removed member, a revoked key or a changed role takes effect promptly.
Credentials#
| Credential | Prefix | Keep it |
|---|---|---|
| Team key | pmfa_ | On your servers only |
| Project token | pmfa_pt_ | On your servers only |
| Client token | pmfa_ct_ | In the browser or app it was minted for, until it expires |
- Keep team keys and project tokens out of browsers, mobile apps, source code and logs. Load them from a secret manager.
- Prefer a project token when an integration works in one project, and grant only the scopes it uses.
- Give browsers and apps a client token with narrow actions, origins, recipients and limits.
- Rotate or revoke a key as soon as you suspect it was exposed. See API keys.
- Never copy a Console session token into an integration. Console sessions and integration credentials are separate.
The MCP endpoint accepts the same credentials. Project tokens need the mcp scope, and client tokens need the mcp action. Every tool then passes through the ordinary API authorization checks. See Authentication for each credential's reach and the full scope list.
Webhook integrity#
Native deliveries carry X-Webhook-Signature, and Meta-format deliveries carry X-Hub-Signature-256. Both are an HMAC-SHA256 of the raw request body, keyed with the endpoint's signing secret.
- Verify the signature over the raw bytes before you parse the body.
- Compare signatures in constant time.
- Deduplicate on the event
id, because a captured request can be sent again and deliveries can repeat. - Store signing secrets like API keys, and rotate a secret that may have leaked. Rotation keeps the previous secret valid for the overlap you choose.
See the webhooks quickstart for a working handler.
Message processing and storage#
Polymorfa processes message content to deliver it to your application. For a Linked Devices Number, Polymorfa holds the session's Signal keys and decrypts each message before delivery. A signed webhook proves that Polymorfa sent the delivery; it does not hide the message body from Polymorfa.
Hosted message history is off by default. When you turn on Hosted Message Storage for a Number, Polymorfa keeps that Number's messages under its retention settings. Hosted storage does not keep attachment files, so download them into your own storage while WhatsApp still serves them. Without hosted storage, the message history API has no stored archive for the Number. Delivery records and operational metadata have their own purposes and retention, so turning hosted history off does not remove every record. See Message history for enablement, beta access, and retention.
Data and hosting regions #
Your Console accounts, settings and secrets are hosted in the EU, in Germany with backups in Finland. WhatsApp sessions and message processing run in Polymorfa's Brazil or EU messaging region, according to the number's assigned region. Messages also pass through the network edge and WhatsApp's own servers; the regional boundary describes Polymorfa's session storage and processing.
Polymorfa's Data Processing Addendum defines its GDPR processing obligations and agreed storage locations. The ANPD recognizes the EU as adequate for LGPD international transfers under Resolution 32/2026. That decision covers the transfer mechanism; your other LGPD obligations still apply.
Audit and monitoring#
- Use Audit history to see who did what in your team, including the actor, action, resource, result, source, IP address and changed fields.
- Use Request logs to review the API requests made with your keys.
- Turn on API key first use alerts to learn when a new key is first used. See API keys.
Report a vulnerability#
For security disclosures or current compliance material, use polymorfa.com/security or email security@polymorfa.com.