Authentication

Every call to the Wappfy API is authenticated with an API key that belongs to one connection (one WhatsApp number).

One key, one connectionCopy Anchor Link

• A key looks like wpf_ followed by random characters. The dashboard shows its first characters as a prefix, so you can tell keys apart.
• A key only reaches the connection it was generated for. Routes never take a connection id: the key already says which connection it is, and it cannot reach any other.
• To use two numbers, generate one key on each connection.
• A key only works while the account's subscription is active. Otherwise every call answers 402 sem_assinatura until the plan is reactivated.

Sending the keyCopy Anchor Link

Use either header. If both are present, X-Api-Key wins.

curl https://app.wappfy.io/api/v1/instance \
  -H "X-Api-Key: wpf_YOUR_KEY"

curl https://app.wappfy.io/api/v1/instance \
  -H "Authorization: Bearer wpf_YOUR_KEY"

Authorization: Bearer is what n8n, Make and most HTTP libraries offer out of the box.

Generating a keyCopy Anchor Link

1. In the dashboard, open Connections and the connection you want.
2. On the Integrations tab, click Generate key on the API card.
3. Give it a name (up to 60 characters) that tells you where it is used, such as n8n or CRM, and click Generate.
4. Copy the key and store it safely.

Only the owner of a connection can generate and revoke its keys. People the connection was shared with cannot.

The API card lists every active key with its name, prefix, creation date and when it was last used.

Up to 3 active keysCopy Anchor Link

Each connection can have up to 3 active keys. That is enough for one key per system, and to rotate a key without downtime:

To generate a fourth key, revoke one you no longer use first.

Revoking a keyCopy Anchor Link

Click Revoke next to the key on the API card. It stops working immediately, and this cannot be undone. Any system still using it starts getting 401 chave_invalida.

Idempotency-KeyCopy Anchor Link

Every route that changes something (POST, PUT, PATCH and DELETE) accepts an optional Idempotency-Key header: 1 to 255 visible ASCII characters, no spaces, such as a UUID or your workflow run id. Repeating the same value with the same API key within 24 hours returns the first response, with the header idempotent-replayed: true, without doing it again.

curl -X POST https://app.wappfy.io/api/v1/messages/text \
  -H "X-Api-Key: wpf_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7d0c1f9e-5b7a-4a52-9a49-2f1b0e6d3c11" \
  -d '{ "to": "5581999999999", "text": "Your appointment is confirmed." }'

Send it whenever your system may retry on its own (n8n and Make retry on timeout). The rules are in Response format.

Authentication errorsCopy Anchor Link

A route that doesn't exist answers 404 rota_nao_encontrada, but only after a valid key: without one, you get 401.

Keep keys safeCopy Anchor Link