Authentication and headers

Before sending API requests

Use this page before testing an API endpoint, scanner postback, inbound provider webhook or outbound WebRiskOps webhook receiver. The goal is to choose the right authentication header, decide whether `Idempotency-Key` applies, and confirm signing inputs before any request carries customer data.

• Use placeholder values only; never paste real API keys, webhook secrets, tokens or customer data into documentation examples.
• Prefer named environment variables such as `WEBRISKOPS_API_TOKEN`, `WRO_SCANNER_SHARED_SECRET`, `WEBRISKOPS_EMAIL_WEBHOOK_SECRET` or `WEBRISKOPS_WEBHOOK_SECRET`.
• Keep headers visible but keep secret values out of docs, logs, tickets and screenshots.

Choose the correct authentication header

Follow the path `API overview → Endpoint page → Header selection → Idempotency or signature check → Request example → Retry and error handling`.

1. Open /docs/api and choose the endpoint page for the request you are building. Result: the required auth header, payload schema and retry rule are visible before you send anything.
2. For customer or integration API calls, send `Authorization: Bearer ${WEBRISKOPS_API_TOKEN}`. Result: the request authenticates without putting the token in the URL, JSON body, logs or screenshots.
3. For scanner result postbacks, send `X-Scanner-Secret: ${WRO_SCANNER_SHARED_SECRET}` to `POST /api/scanner/results`. Result: missing or invalid scanner secrets return UNAUTHORIZED without echoing the submitted value.
4. For inbound email webhooks, send `X-Email-Webhook-Secret: ${WEBRISKOPS_EMAIL_WEBHOOK_SECRET}` to `POST /api/email/webhook`. Result: inbound email events are accepted only from the configured provider path.
5. For Shopify compliance webhooks, validate `X-Shopify-Hmac-Sha256` against the raw request body. Result: SIGNATURE_INVALID stops the webhook before compliance records are written.
6. For outbound ticket export webhook receivers, verify `X-WebRiskOps-Signature` with `X-WebRiskOps-Timestamp` and `X-WebRiskOps-Nonce`. Result: receivers can reject WEBHOOK_SIGNATURE_INVALID and replayed payloads before creating downstream work.
7. Add `Idempotency-Key` for retriable client calls, scanner postbacks and automation examples. Result: a repeat request for the same logical event does not create duplicate work, and IDEMPOTENCY_CONFLICT is reserved for a reused key with a different payload.
8. Send `Content-Type: application/json` and `Accept: application/json` on JSON endpoints. Result: validation, auth and rate-limit responses use a predictable JSON structure.
9. Rotate secrets in the provider or environment first, then update the WebRiskOps target or integration setting. Result: old secrets stop authorizing new requests without exposing raw values in documentation.
10. Continue to Request and response examples or the endpoint-specific page. Result: developers can test with placeholders, then troubleshoot failures through Errors, idempotency, retries and rate limits.

Configure idempotency and signing headers

Each header has a narrow purpose; do not substitute one secret or signature model for another.

• `Authorization` is for authenticated customer or integration API calls that use a bearer token.
• `X-Scanner-Secret` is only for scanner result postbacks from the scanner runtime.
• `X-Email-Webhook-Secret` is only for inbound email provider webhooks.
• `X-Shopify-Hmac-Sha256` is the Shopify provider signature and must be checked against the raw request body.
• `X-WebRiskOps-Signature`, `X-WebRiskOps-Timestamp` and `X-WebRiskOps-Nonce` are for outbound WebRiskOps ticket export webhooks.
• `Idempotency-Key` should stay stable for the same logical request and change when the payload meaning changes.
• Secret fingerprints, connected status and last validation state may be shown; raw secret material should not be displayed.

Ready authentication states

Continue only when the request can authenticate and retry safely.

• Bearer ready means Authorization uses a configured API token, not a token pasted into a URL or payload.
• Scanner secret ready means `X-Scanner-Secret` matches the configured scanner shared secret.
• Email webhook ready means `X-Email-Webhook-Secret` matches the configured inbound email secret.
• Provider signature ready means the Shopify or outbound WebRiskOps signature is verified against the raw body and expected timestamp or nonce inputs.
• Idempotency ready means `Idempotency-Key` maps to one logical request and is reused only for safe retries.
• JSON header ready means `Content-Type` and `Accept` are both `application/json` when the endpoint expects JSON.

Blocked authentication states

Blocked auth states should explain exactly what to fix without leaking secrets.

• `UNAUTHORIZED` means a required bearer token or shared-secret header is missing, invalid or not configured.
• `SIGNATURE_INVALID` means a provider HMAC header does not match the raw request body and configured secret.
• `WEBHOOK_SIGNATURE_INVALID` means an outbound WebRiskOps webhook receiver rejected the signature, timestamp, nonce or raw-body calculation.
• `IDEMPOTENCY_CONFLICT` means the same `Idempotency-Key` was reused with a different logical payload.
• Missing JSON headers can produce validation responses that do not match the examples.
• A secret value in a URL, payload, screenshot, ticket or log should be rotated before retrying.

Continue after authentication setup

Continue to Scanner results API, Inbound email webhook, API ticket export webhooks or Extension and platform handoffs when the relevant header is ready. Use Request and response examples for copyable placeholder requests, then use Errors, idempotency, retries and rate limits when a request is rejected or safely retried.