Authenticate requests

# Authenticate requests

Canonical: https://docs.flowrelay.app/setup/authentication/
Markdown: https://docs.flowrelay.app/setup/authentication.md

FlowRelay authenticates incoming events before it records the receipt and hands a trigger to Shopify Flow.

## Steps
Complete these in order.
1. Choose the sending service
   Select Zapier, Make, n8n, or custom HTTP/code when creating the endpoint. This tells FlowRelay what will make the POST request; it does not change the Shopify Flow trigger variant.
2. Use the compatible preset
   FlowRelay selects static-header authentication for Zapier, Make, and n8n, and exact-body HMAC-SHA256 for custom HTTP/code.
3. Override only deliberately
   A capable sender may use the advanced override. Keep HMAC when the sender can calculate a digest over the exact raw request bytes; do not select it for a standard no-code webhook step that cannot do so.
4. Send a synthetic test
   Send a test event with synthetic data and use the receipt to confirm authentication passed before connecting real production events.
5. Diagnose authentication failures
   If authentication fails, share the FlowRelay support code or diagnostics share. Do not paste secrets, full authentication headers, signatures, or raw event bodies into support.

## Bearer, HMAC formats, and HS256 JWT
Bearer mode expects Authorization: Bearer followed by the private token. Scheme casing is ignored; duplicate or ambiguous values are rejected. Authentication never falls through to another mode. Static-header presets for n8n, Make, and Zapier remain available.

HMAC mode signs the original request body bytes. Set hex or Base64 and the exact prefix, such as sha256=. Configure the header name explicitly. The GitHub documented format is X-Hub-Signature-256 with prefixed hex; Typeform documents Typeform-Signature with prefixed Base64. FlowRelay protocol fixtures cover these formats; they do not establish complete live sender compatibility. Check event fields, sender retries, and a real end-to-end test before adopting a named integration. Stripe's timestamped signature format is not supported by this generic verifier.

HS256 JWT is an advanced shared-secret mode. Configure the expected issuer and audience. Tokens must include expiry, issuer, and audience; not-before is checked when present. Clock tolerance is configured from zero to 60 seconds. Only HS256 is allowed; token-supplied key URLs and alternative algorithms are rejected. This is not OAuth or public-key JWT verification.

For sender-owned signing secrets, review a credential change in Endpoint setup and enter 32–512 UTF-8 bytes in the private confirmation form. Secrets are encrypted and omitted from exports. Generated credentials are revealed once. FlowRelay does not offer an unauthenticated endpoint mode.

- [GitHub signature documentation](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries)
- [Typeform signature documentation](https://www.typeform.com/developers/webhooks/secure-your-webhooks/)

## Choose the authentication mode
HMAC binds authentication to the exact body bytes and remains the stronger custom-code path. Static-header authentication is the compatible normal path for Zapier, Make, and n8n. Bearer and HS256 JWT are also available for senders that use those formats. Credentials can be generated in FlowRelay or supplied privately by the sender owner.


- Mode: HMAC-SHA256; Use when: Custom HTTP/code or another sender can sign the exact request body; Operator note: Recommended for capable senders because the digest authenticates both the shared secret and the exact body bytes.
- Mode: Static-header auth; Use when: Zapier, Make, n8n, or another sender can attach a fixed secret header but cannot calculate FlowRelay's exact-body HMAC; Operator note: FlowRelay selects this automatically for the standard no-code profiles. Keep the value private and rotate it if it is exposed or the sender relationship changes.

## Request wire contract
Send JSON with POST to the endpoint URL and put authentication in that endpoint's configured header. FlowRelay compares a static value exactly, verifies a Bearer token, checks configured HS256 JWT claims, or verifies HMAC-SHA256 over the exact raw request bytes. HMAC encoding and literal prefix must match the endpoint settings; the legacy default remains unprefixed hex. Parsing, reformatting, re-encoding, or otherwise changing the body after signing invalidates the HMAC signature.

### HMAC sender pseudocode
Keep placeholders private and sign the same bytes the sender transmits.

```text
body_bytes = utf8_encode(exact_json_body)
signature = lowercase_hex(hmac_sha256(FLOWRELAY_SIGNING_SECRET, body_bytes))
POST FLOWRELAY_ENDPOINT_URL
Content-Type: application/json
FLOWRELAY_CONFIGURED_AUTH_HEADER: signature
Body: body_bytes
```

### Static-header synthetic request
Replace placeholders only inside the sender's trusted configuration.

```sh
curl -X POST "$FLOWRELAY_ENDPOINT_URL" \
  -H "Content-Type: application/json" \
  -H "$FLOWRELAY_CONFIGURED_AUTH_HEADER: $FLOWRELAY_STATIC_SECRET" \
  --data-binary '{"event_type":"synthetic.test","external_event_id":"synthetic-001"}'
```


- Requirement: Method and media type; HMAC-SHA256: POST with Content-Type: application/json; Static header: POST with Content-Type: application/json
- Requirement: Configured auth header; HMAC-SHA256: Use the configured hex or Base64 encoding and literal prefix in the exact header shown for this endpoint; Static header: Put the exact generated secret value in the exact header name shown for this endpoint.
- Requirement: Comparison input; HMAC-SHA256: HMAC the exact raw body bytes that are sent on the wire; Static header: Compare the configured header value exactly.

## Success check
A test receipt shows that authentication passed before you enable production traffic. If authentication fails, fix the sender configuration and send a new test event with synthetic data.


## Safe troubleshooting
FLR_AUTH_HEADER_MISSING means the configured header name was absent. FLR_AUTH_FAILED means the configured static, Bearer, exact-body HMAC, or HS256 JWT credential did not verify. Two newest consecutive outside authentication failures within 30 minutes can prompt a guided, non-destructive replacement endpoint; the original remains active until you separately delete it. Correct the sender configuration and send a fresh event; do not replay an unauthenticated request. Share only the support code or a diagnostics share when someone needs help. Do not share the secret, full authentication header value, signature, raw event body, Shopify token, session data, or copied merchant incident.


## Handoff Boundary
Delivered means FlowRelay handed the trigger to Shopify Flow. It does not mean downstream Shopify Flow branches, app calls, fulfillment changes, emails, or later systems completed.

## Related
- [Event types and payloads](https://docs.flowrelay.app/setup/event-types-and-payloads.md)
- [Trigger variants and mapping](https://docs.flowrelay.app/setup/trigger-variants-and-event-mapping.md)
- [Add the Shopify Flow trigger](https://docs.flowrelay.app/setup/shopify-flow-trigger.md)
- [Share diagnostics](https://docs.flowrelay.app/recover/diagnostics.md)

## Safety Boundary
Do not share endpoint secrets, authentication headers, HMAC values, tokens, raw event bodies, customer records, Shopify sessions, store passwords, or database URLs in public examples.