Authentication

The three header methods PrivacyFlow accepts and which credential type allows which, with a curl example for each.

Every authenticated PrivacyFlow request carries one API key in one of three HTTP headers. The header you’re allowed to use is determined by the credential type the dashboard issued. This page is the full matrix.

The three header methods

The API reads the key from one of three locations, in priority order. If more than one is present, the first match wins.

Which credential types allow which headers

The credential type (set when the dashboard creates it) restricts which of those headers you may send. Send the wrong one and you get 401 Unauthorized.

If a key has no type recorded, the API treats it as api-key for backwards compatibility — so existing keys keep working.

How to choose

• Default to api-key. Issue it from the dashboard Credentials section. Use Authorization: Bearer <key> for any HTTP client and you’re done.
• Use webhook-bearer only when you’re configuring inbound webhook delivery to a receiver that speaks Bearer natively. The key can still poll and send over Bearer, so it doubles as a test credential.
• Use webhook-header only when your receiver is a service that needs a dedicated header (e.g., some n8n webhook auth schemes). It can only authenticate via X-Webhook-Token; it cannot use Bearer.

curl examples — all three methods, all three types

api-key via Bearer

curl "$PRIVACYFLOW_BASE_URL/api/v1/auth/verify" \
  -H "Authorization: Bearer $PRIVACYFLOW_API_KEY"

api-key via X-API-Key

curl "$PRIVACYFLOW_BASE_URL/api/v1/auth/verify" \
  -H "X-API-Key: $PRIVACYFLOW_API_KEY"

webhook-bearer (Bearer only)

curl "$PRIVACYFLOW_BASE_URL/api/v1/auth/verify" \
  -H "Authorization: Bearer $PRIVACYFLOW_API_KEY"

webhook-header (X-Webhook-Token only)

curl "$PRIVACYFLOW_BASE_URL/api/v1/auth/verify" \
  -H "X-Webhook-Token: $PRIVACYFLOW_API_KEY"

What happens on a mismatch

Sending a header your credential type doesn’t allow returns:

HTTP/1.1 401 Unauthorized
{ "error": "Authentication method not allowed for this credential type" }

Sending any of the three headers with an invalid key returns:

• 401 Unauthorized on /api/v1/auth/verify
• 403 Forbidden on /api/v1/messages/poll and /api/v1/messages/send

The intentional 401-vs-403 split lets you distinguish “wrong header method” (a config bug) from “wrong key” (a secret bug) in your logs. See errors and limits for the full status table.

Rotating and revoking keys

The dashboard Credentials section lets you replace or delete a key. Replacing keeps the same credentialId, so rate-limit buckets and any webhook auth configured against the key keep working; only the key string changes. Deleting frees the credentialId immediately.