Seguridad
Una credencial por aplicación y ambiente.
Todas las operaciones de negocio usan autenticación Bearer. La identidad del cliente se resuelve desde la credencial y nunca desde un campo manipulable de la petición.
Cabecera de autenticación
Incluye la credencial en cada petición HTTPS al API:
Authorization: Bearer <credencial-del-conector>Scopes disponibles
Aplica mínimo privilegio: cada aplicación recibe únicamente las capacidades necesarias para su función.
| Scope | Permite |
|---|---|
connections:read | Consultar conexiones visibles para tu cliente. |
connections:credentials:write | Registrar o rotar la API key de MensaGlobal de una conexión propia. |
connections:services:propose | Declarar la lista de códigos MensaGlobal contratados para revisión por SendingBay. |
articles:read | Consultar artículos canónicos y capacidades habilitadas. |
shipments:read | Consultar envíos propios. |
shipments:write | Crear envíos. |
tracking:read | Consultar el historial de seguimiento propio. |
locations:read | Buscar puntos de entrega y recogida de una conexión propia. |
webhooks:read | Consultar suscripciones y entregas propias. |
webhooks:write | Crear, modificar, rotar y reintentar webhooks propios. |
Credenciales de MensaGlobal
Si utilizás MensaGlobal, registrás tu propia API key para cada conexión. Es distinta de la credencial con la que accedés al Conector y no se envía al crear cada envío. SendingBay crea primero la conexión inactiva y te facilita su identificador.
Una aplicación de gestión de tu empresa, con el scope específico, podrá enviar la clave mediante PUT /v1/carrier-connections/{connection_id}/credentials/mensaglobal. El API sólo confirma que quedó configurada: nunca devuelve la clave. Registrar o rotar una clave deja la conexión inactiva hasta que SendingBay la valide.
Servicios contratados de MensaGlobal
Tu backend puede declarar los códigos que MensaGlobal te haya facilitado para esa API key. Enviá la lista con el scope connections:services:propose y una cabecera X-Idempotency-Key estable para el intento.
{"codes":["13H","24H"]}La operación POST /v1/carrier-connections/{connection_id}/service-proposals responde 202. Los códigos quedan pendientes de revisión por SendingBay: declararlos no los habilita para crear envíos. Si repetís la misma clave de idempotencia con otra lista, recibís 409.
Ciclo de vida de una credencial
- EmitirSendingBay la asocia a cliente, aplicación, ambiente, scopes y vencimiento.
- GuardarEl valor completo se muestra una sola vez y debe entrar directamente en un gestor de secretos.
- RotarCrea una credencial nueva, despliégala, verifica el tráfico y luego revoca la anterior.
- RevocarLa revocación de una aplicación no afecta las credenciales del transportista ni otras integraciones.
Errores esperables
401authentication_requiredFalta la cabecera Bearer.401invalid_credentialLa clave no es válida, venció o fue revocada.403insufficient_scopeLa identidad existe, pero no autoriza esa operación.