Permisos y scopes
Cada API key tiene un conjunto de scopes que definen qué puede hacer. El shape con el que se guardan no es una lista plana de strings — es un objeto anidado por recurso:
interface ApiKeyScope {
resource: string;
permissions: ApiKeyPermission[];
}
// ej: { resource: 'orders', permissions: ['read', 'update'] }Este es el shape que seleccionas en el formulario de creación (checkboxes de recurso × permiso). La conversión al formato resource:action que usa el resto de la plataforma para autorizar (el mismo que ves en las tablas de "Permiso requerido" de cada endpoint) ocurre en el momento de autenticar cada petición, no cuando creas la llave.
Recursos seleccionables
El panel permite elegir entre estos recursos al crear una llave:
products, orders, customers, channels, inventory, reports, o el comodín * (todos).
reports no es un recurso del catálogo de permisos
El selector del panel incluye reports como opción, pero el catálogo canónico de permisos de la plataforma no tiene un recurso llamado reports — el recurso equivalente en el resto del sistema se llama insights. Si automatizas la creación de scopes fuera del panel, ten en cuenta esta diferencia de nombre.
Este es además un subconjunto reducido: la plataforma internamente reconoce muchos más recursos (devoluciones, integraciones, ubicaciones, envíos, configuración, notificaciones, categorías, facturación, CFDI, y más), pero solo estos 6 (+ el comodín) están disponibles al crear una API key desde el panel hoy.
Permisos disponibles
El vocabulario de permisos de una API key es más amplio que solo lectura/escritura:
*, read, write, update, delete, create, sync, manage, import, export, fulfill, cancel, configure, connect, disconnect, adjust, transfer, count, track
No cubre todas las acciones de la plataforma
Este vocabulario no coincide 1:1 con las acciones que existen en el catálogo canónico de permisos internos (por ejemplo, acciones como aprobar o procesar, que sí existen en otras partes del sistema, no tienen equivalente en una API key). Si tu integración necesita una acción muy específica de un recurso, valida primero que esté en la lista de arriba.
Conversión a resource:action
Cuando autenticas una petición, cada scope se convierte a uno o más strings resource:action siguiendo estas reglas:
| Scope de entrada | Se convierte a |
|---|---|
{ resource: '*', permissions: ['*'] } | ['*:*'] |
{ resource: '*', permissions: ['read', 'write', 'delete'] } | ['*:*'] (regla de compatibilidad retroactiva — solo con exactamente esos 3 permisos) |
{ resource: 'orders', permissions: ['*'] } | ['orders:*'] |
{ resource: 'orders', permissions: ['read', 'update'] } | ['orders:read', 'orders:update'] (un string por permiso) |
Cómo se evalúan al autorizar
Al validar si una API key puede ejecutar una acción, la plataforma revisa en este orden:
*:*— coincidencia exacta con el comodín global.resource:action— coincidencia exacta.resource:*— comodín de recurso.*:action— comodín de acción.
Basta con que uno de los permisos de la key haga match en cualquiera de estos cuatro pasos para autorizar la petición.
Quién puede definir y modificar scopes
Solo quien puede gestionar API keys puede definir sus scopes — hoy, únicamente el o los owners del tenant (ver Gestión de API Keys). No hay una pantalla separada para editar los scopes de una llave existente: para cambiar los permisos de una integración tienes que crear una llave nueva con el scope correcto y revocar la anterior.