Authentication

There are two distinct trust boundaries in a Swoop POS integration. Keep them separate.

1. Webhooks into the adapter — shared-secret token

Every status webhook and every Pub/Sub push delivery must carry a shared-secret token as the token query parameter:

POST /webhook/{integration}/{locationId}?token=YOUR_WEBHOOK_TOKEN

• The adapter compares it against its configured PUBSUB_PUSH_TOKEN.
• A missing or mismatched token is rejected with 401 Unauthorized.
• If no token is configured server-side, the check is skipped — local/dev only; never run production without a token.

This token authenticates that the caller is allowed to deliver events. It does not identify a specific order or member.

Webhook payload verification

The adapter passes all request headers through to your provider's WebhookTranslator. If your POS signs webhooks (e.g. an HMAC over the body), verify that signature inside TranslateWebhook before trusting the payload — the token guards the endpoint, the signature guards the message. A payload that fails verification should be treated as poison: return no event so the adapter acks and drops it (see Errors).

2. The adapter into your POS — provider credentials

When the adapter calls your POS to create an order, it authenticates with credentials you define in the provider's tenant config (ProviderConfig). These are provider-specific and stored server-side as secrets — never in the spec or in source.

Example: an OAuth2 integration

A common pattern is OAuth2 authorization-code + refresh:

• One-time consent yields a long-lived refresh token (offline_access scope).
• The integration exchanges it for short-lived access tokens as needed.
• Config keys typically include baseURL, tokenURL, clientID, clientSecret, refreshToken, plus whatever location/store ids your POS requires.

Your integration chooses its own auth scheme — API key, OAuth, mTLS — by reading whatever keys it needs from its tenant config. Swoop stores those keys server-side as secrets and supplies them at startup.

Secrets handling

• Credentials live in environment variables / a secret manager, surfaced to providers via ProviderConfig. They are never committed (.env, secrets/ are git-ignored).
• The webhook token and your POS credentials are rotated independently.