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. Ask the sender owner whether their system can sign requests with HMAC-SHA256.
2. Choose HMAC-SHA256 when signing is available, then store the generated signing secret only in the sender system.
3. Choose static-header auth only when the sender cannot sign requests, then store the generated header name and value privately.
4. Send a synthetic test event and use the receipt to confirm authentication passed before connecting real production events.
5. If authentication fails, share the FlowRelay error code or diagnostics package. Do not paste secrets, full headers, signatures, or raw request bodies into support.

## Choose the authentication mode
Prefer signed requests when the sender supports them. Use static-header authentication only when the sender cannot sign safely.


- Mode: HMAC-SHA256; Use when: The sender can sign the request body.; Operator note: Best default for production senders because FlowRelay can verify the sender knows the shared secret.
- Mode: Static-header auth; Use when: The sender cannot create HMAC signatures.; Operator note: Keep the generated header value private and rotate it if it is exposed or the sender relationship changes.

## 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 synthetic event.


## Support-safe troubleshooting
Share the FlowRelay error code or a diagnostics package when someone needs help. Do not share the secret, full header value, signature, raw 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)
- [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 include raw payloads, endpoint secrets, auth headers, HMAC values, Shopify tokens, Shopify sessions, database URLs, customer data, merchant incidents, or copied private logs in public examples.