Scopes y permisos

Scopes

Cada API key se genera con uno de estos scopes:

Scope	Acceso	Cuándo usar
`READ`	Solo lectura	Sistemas de reporting, observabilidad, BI
`WRITE`	Lectura + operaciones financieras	Servicios que disparan retiros/recaudos
`SWAP`	Solo la Conversión COP→USDT (`/swaps/*`)	Servicios que compran USDT con tus pesos

WRITE es un superset de READ: cualquier endpoint que acepta READ también acepta WRITE.

El scope `SWAP` es exacto

SWAP no se hereda de WRITE ni de READ, y tampoco los reemplaza:

Una llave WRITE o READ que llama a /swaps/* recibe 403 INSUFFICIENT_SCOPE.
Una llave SWAP que llama a cualquier ruta fuera de /swaps/* recibe 403 SCOPE_ROUTE_FORBIDDEN.
Solo puedes crear una llave SWAP si Mouv habilitó el servicio de conversión para tu empresa. Si no, la creación responde 403 SWAPS_NOT_ENABLED.
Opcionalmente, una llave puede restringirse a una lista de IPs (allowedIps); es recomendado para llaves SWAP. Una petición desde otra IP recibe 403 IP_NOT_ALLOWED. Ver Autenticación.

Permiso adicional: “Gestionar billeteras”

Una llave SWAP puede tener, además, el permiso Gestionar billeteras, que le permite registrar y eliminar billeteras de tu empresa por API (POST y DELETE /swaps/wallets). No es un scope nuevo: es una capacidad adicional del scope SWAP.

Solo existe en llaves SWAP; pedirlo con otro scope responde 400 INVALID_SCOPE_COMBINATION.
Exige allowedIps (400 IP_ALLOWLIST_REQUIRED si faltan) y que Mouv haya habilitado la función para tu empresa (403 WALLET_API_NOT_ENABLED).
Se define al crear la llave, en el dashboard y con 2FA; no se puede agregar después a una llave existente.
Máximo 2 llaves vigentes con el permiso por empresa (409 WALLET_API_KEY_LIMIT).
Una llave SWAP sin el permiso recibe 403 WALLET_PERMISSION_REQUIRED en el alta y la baja, pero puede listar y consultar billeteras.

Detalle en Conversión COP→USDT y Autenticación.

Tabla de permisos por endpoint

Endpoint	READ	WRITE
`GET /wallets/balance`	✅	✅
`GET /wallets/transactions`	✅	✅
`GET /wallets/transactions/:id`	✅	✅
`GET /wallets/transactions/:id/receipt.pdf`	✅	✅
`GET /deposits`	✅	✅
`GET /wallets/deposits/:id/receipt.pdf`	✅	✅
`POST /transfers/resolve-key`	❌	✅
`POST /transfers/quote`	❌	✅
`POST /transfers/quote/ach`	❌	✅
`POST /transfers/send`	❌	✅
`POST /deposits/pse`	❌	✅
`POST /deposits/:id/share-email`	❌	✅

Los endpoints /swaps/* solo aceptan el scope SWAP:

Endpoint	READ	WRITE	SWAP
`GET /swaps/me`	❌	❌	✅
`GET /swaps/networks`	❌	❌	✅
`GET /swaps/wallets`	❌	❌	✅
`GET /swaps/wallets/:walletId`	❌	❌	✅
`POST /swaps/wallets`	❌	❌	✅ con permiso “Gestionar billeteras”
`DELETE /swaps/wallets/:walletId`	❌	❌	✅ con permiso “Gestionar billeteras”
`POST /swaps/quotes`	❌	❌	✅
`POST /swaps`	❌	❌	✅
`GET /swaps`	❌	❌	✅
`GET /swaps/:id`	❌	❌	✅
`GET /swaps/:id/receipt.pdf`	❌	❌	✅

Respuestas de scope insuficiente

Si una llave READ intenta una operación WRITE:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "INSUFFICIENT_SCOPE",
  "required": "WRITE",
  "granted": "READ",
  "message": "Esta operación requiere una API key con permiso WRITE"
}

Multi-tenant scope (automático)

Tu API key está bound a UNA cuenta empresarial. Todos los endpoints filtran por tu companyId automáticamente — no podés ver ni operar datos de otras cuentas. Endpoints administrativos globales (/admin/*) usan un middleware de autenticación diferente y rechazan API keys cliente. Esto es defense-in-depth contra privilege escalation.

Multi-sig (firma múltiple)

Si tu empresa configuró multiSigThreshold >= 2, las transferencias salientes vía POST /transfers/send no se dispatchan inmediatamente:

{
  "status": "AWAITING_APPROVAL",
  "approvalId": "appr_...",
  "threshold": 2,
  "expiresAt": "2026-05-26T20:00:00.000Z"
}

La transacción espera firmas (ADMIN/OPERATOR roles via dashboard) hasta alcanzar el quorum. TTL 24h — si no se firma, expira y revierte automáticamente. API keys NO pueden firmar approvals (defense-in-depth — un actor humano siempre debe verificar). Las firmas se hacen desde el dashboard cliente o admin.

Buenas prácticas

Mínimo privilegio

Generá llaves READ separadas para reporting/observabilidad. Solo usá WRITE en servicios que estrictamente disparan movimientos.

Múltiples llaves por entorno

production-server · staging · local-dev · reporting-bi. Cada una con su label y su scope mínimo necesario.

Rotá cada 90 días

Cero downtime: generá nueva → switch → revocá vieja.

Audit por llave

El campo apiKeyId queda persistido en cada Transaction — podés filtrar el historial por llave para forensics.

Comenzar

Saldos

Retiros (Outflows)

Recaudos PSE

Recaudos Bre-B (agregadores)

Conversión COP→USDT

Transacciones

Referencia

Scopes y permisos

Scopes

El scope `SWAP` es exacto

Permiso adicional: “Gestionar billeteras”

Tabla de permisos por endpoint

Respuestas de scope insuficiente

Multi-tenant scope (automático)

Multi-sig (firma múltiple)

Buenas prácticas

Mínimo privilegio

Múltiples llaves por entorno

Rotá cada 90 días

Audit por llave

Scopes

El scope SWAP es exacto

Permiso adicional: “Gestionar billeteras”

Tabla de permisos por endpoint

Respuestas de scope insuficiente

Multi-tenant scope (automático)

Multi-sig (firma múltiple)

Buenas prácticas

Mínimo privilegio

Múltiples llaves por entorno

Rotá cada 90 días

Audit por llave

El scope `SWAP` es exacto