Autenticación de la REST API para España
Bearer keys, OAuth2 PKCE y mTLS — autenticación de la REST API para clientes en España.
Arquitectura — API keys (servidor a servidor)
Genera API keys en el dashboard con alcance de país (España) y rol (solo lectura, pedidos, facturas, admin). Envíalas como Authorization: Bearer cm_live_… sobre TLS 1.3. Prefijos por entorno (cm_live_, cm_test_) y rotación sin downtime con ventana de solapamiento de 24h. Nunca incrustes keys en código client-side — usa OAuth2 para esos flujos. IVA 21% y otros defaults para España se infieren del scope de la key pero son sobreescribibles por petición en el campo country.
Cómo integrarlo — OAuth2 con PKCE (acceso delegado)
Para apps de usuario final (móvil, SPA, portales de partners) usa OAuth2 authorisation code con PKCE (S256). Autoriza en https://auth.corpmerch.com/oauth2/authorize, intercambia el code por un access token (1 hora) y refresh token (30 días, rotativo al usarse). Scopes con least-privilege: orders.read, orders.write, invoices.read, etc. Los refresh tokens son device-bound; la detección de robo invalida la familia ante reuso.
Operación y casos límite — mTLS (tenants de alta seguridad)
Los clientes Enterprise pueden exigir mTLS además del bearer. Sube tu certificado de cliente (PEM, RSA 2048 o ECDSA P-256) en el dashboard o vía Trust API. Terminamos mTLS en nuestro edge en Madrid, validamos cadena y SAN contra tu config de tenant y solo entonces aceptamos. Rotación de cert con par primary/secondary. La autenticación contra FACe / Suministro Inmediato de Información (SII) corre en nuestro lado con nuestras credenciales — tu mTLS es solo para la API de Corp-Merch.
Preguntas frecuentes
¿Key o OAuth — cuándo?
Server-to-server en tu DC o VPC: API key. Delegación de usuario final (móvil, portales de partners): OAuth2 PKCE. Setups mixtos usan ambos.
¿Cómo roto una key?
Genera una nueva en paralelo, despliega, luego revoca la antigua tras la ventana de 24h. El dashboard muestra last-used timestamps.
¿mTLS es estándar o de pago?
Incluido en Enterprise; add-on en Pro. Certs self-signed aceptados con manual pinning; preferidas CAs públicas.
¿Caducidad de tokens?
Access tokens 1 hora; refresh tokens 30 días, rotativos al uso, con detección de robo.
¿Y la autenticación contra FACe/SII?
FACe/SII es canal downstream — nos autenticamos en tu nombre con nuestras credenciales. El routing IVA 21% es transparente.