Autenticación y contexto de tenant
Autenticá la Integration API desde server-side y usá tenant, scopes y request IDs de forma consistente.
Usá X-API-Key desde server-side
Cada request a la Integration API se autentica con X-API-Key. Guardá la credencial en tu backend, BFF o secret store; no la expongas en browser, app móvil, POS UI, URLs ni bundles públicos.
El tenant de la credencial es la autoridad
El tenant asociado a la API key validada define el contexto de la integración. X-Tenant-ID o X-Tenant-Subdomain, cuando una operación los admite, funcionan como verificaciones de consistencia y deben coincidir con la credencial.
Scopes por operación
GET /api/customers/search→customers.readPOST /api/customers→customers.writePOST /api/purchases→purchases.writeGET /api/customers/{id}/state→customers.read
Tenant válido no significa acceso irrestricto
Cada operación sigue validando el program, customer y los recursos que usa. Un header enviado por el caller no reemplaza esas comprobaciones de ownership.
Separá los actores
- La API key identifica a una integración server-to-server.
- La identidad del cliente pertenece a tu experiencia customer-facing.
- Una sesión de operador POS pertenece a la superficie de operación POS.
- Una identidad administrativa pertenece a su propia superficie.
Correlacioná requests con x-request-id
Podés enviar x-request-id para relacionar una llamada con tus propios logs. Cuando falta o llega vacío, el boundary moderno genera un identificador; usalo para diagnóstico y trazabilidad de tu integración.