# 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](https://docs.polymorfa.com/development/client-tokens) with
  narrow actions, origins, recipients and limits.
- Rotate or revoke a key as soon as you suspect it was exposed. See
  [API keys](https://docs.polymorfa.com/development/api-keys#rotate-a-key).
- 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](https://docs.polymorfa.com/api/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](https://docs.polymorfa.com/development/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](https://docs.polymorfa.com/messaging/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](https://www.polymorfa.com/dpa) defines its
GDPR processing obligations and agreed storage locations. The
[ANPD recognizes the EU as adequate](https://www.gov.br/anpd/pt-br/assuntos/assuntos-internacionais/transferencia-internacional-de-dados)
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](https://docs.polymorfa.com/teams/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](https://docs.polymorfa.com/development/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](https://docs.polymorfa.com/development/api-keys#review-your-keys).

## Report a vulnerability

For security disclosures or current compliance material, use
[polymorfa.com/security](https://www.polymorfa.com/security) or email
**security@polymorfa.com**.

## See also

- [Authentication](https://docs.polymorfa.com/api/authentication)
- [API keys](https://docs.polymorfa.com/development/api-keys)
- [Client tokens](https://docs.polymorfa.com/development/client-tokens)
- [Webhooks](https://docs.polymorfa.com/development/webhooks)
- [Secure your account](https://docs.polymorfa.com/teams/account-security)
- [Choose notifications](https://docs.polymorfa.com/teams/notifications)
