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. Check sender signing support
   Ask the sender owner whether their system can sign requests with HMAC-SHA256.
2. Prefer HMAC-SHA256
   Choose HMAC-SHA256 when signing is available, then store the generated signing secret only in the sender system.
3. Use static auth when necessary
   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
   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.

## 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: Preferred 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.

## 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 or verifies a lowercase hexadecimal HMAC-SHA256 digest over the exact raw request bytes. 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: Put the lowercase hexadecimal SHA-256 digest in the exact header name 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 static value or exact-body HMAC did not verify. 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.