Authentication

Partner external integrations

Use the X-API-Key header for partner external endpoints such as /api/partner/*.

X-API-Key: sk_live_your_api_key

Auth is API key only. There is no X-API-Secret / x-api-secret requirement on the live guard.

Credential SSOT

Store	Contents
`partner_api_keys`	API keys used for auth (mint via regenerate / create)
`partner_webhooks.secret`	Preferred webhook HMAC secret
`seller_profiles.api_configuration`	Metadata + `apiEnabled` only (no plaintext `apiKey` / `apiSecret`)

enableApi toggles access flags / key activation. It does not mint a new key — remint is Regenerate only (once-reveal). Regenerate returns { apiKey } only — there is no functional apiSecret.

Admin/settings webhookUrl updates the latest active partner_webhooks.url (no secret remint). Clearing deactivates active rows. First webhook rows come from approve/portal create (once-reveal).

Webhook URL safety (SSRF): store and outbound delivery accept only public HTTPS. Private/metadata hosts (localhost, RFC1918, link-local, cloud metadata) are rejected. Outbound HTTP uses maxRedirects: 0 and a pinned DNS lookup so the hostname cannot rebind to a private/metadata address after validation.

Example

curl -X GET "https://service-gateway.loscenotes.com/api/partner/cenotes" \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json"

Other auth models in the platform

Partner portal and management endpoints use JWT
Some shared public endpoints do not require API key auth
Some operational endpoints, such as on-site checkout confirmation, require role-based authenticated access

Sandbox & WebSocket

Partner sandbox is live: mint sk_test_ keys, generate/reset sandbox data via the partner portal. Data uses the isolated partners_sandbox schema (not production tables).
sk_test_ cannot call /api/partner/* (or other production partner routes). The guard allows sandbox keys only on /api/partner-sandbox/* and /api/partner/webhooks/simulator/*. Elsewhere → Forbidden error.partner.sandbox_key_not_allowed_on_production_api. Use sk_live_ for all /api/partner/* examples.
Partner WebSocket realtime is shipped: PartnerRealtimeGateway at path /partner/ws (JWT portal user or API key key_hash; sk_live_* only — sandbox keys rejected). See internal docs/partners/03-WEBSOCKET-REAL-TIME.md for event fan-out and CORS.

Error shape

Current API errors are returned in the enhanced global format:

{
  "success": false,
  "message": "validation.invalid_data",
  "error": "Bad Request",
  "statusCode": 400,
  "timestamp": "2026-03-10T18:00:00.000Z",
  "path": "/api/partner/cenotes"
}

Partner external integrations​

Credential SSOT​

Example​

Other auth models in the platform​

Sandbox & WebSocket​

Error shape​