Skip to main content

API key

Toda llamada a la API requiere un header Authorization: Bearer <API_KEY> donde <API_KEY> es la llave plana que se entregó una sola vez al crearla.
Las llaves comienzan con el prefijo mvk_ seguido de ~96 bits de entropía (32 caracteres base64url). Cada llave es bound a UNA cuenta empresarial y NO es transferible.

Generar una llave

  1. Iniciá sesión en consola.mouvlatam.com
  2. Navegá a API keys en el menú lateral
  3. Click Generar nueva llave
  4. Ingresá un label descriptivo (ej. production-server, staging, reporting-readonly)
  5. Elegí el scope: READ (solo lectura) o WRITE (lectura + operaciones financieras)
    • SWAP (solo la Conversión COP→USDT) está disponible únicamente si Mouv habilitó el servicio para tu empresa; si no, la creación responde 403 SWAPS_NOT_ENABLED.
  6. Opcional: define allowedIps (string[]), la lista de IPs desde las que se puede usar la llave. Si la defines, una petición desde otra IP recibe 403 IP_NOT_ALLOWED. Es recomendado para llaves SWAP: usa las IPs de salida de tus servidores. Si no la defines, la llave funciona desde cualquier IP. Acepta IPs sueltas o rangos CIDR (hasta /24 en IPv4 y /48 en IPv6), máximo 20 entradas; una lista inválida responde 400 INVALID_ALLOWED_IPS.
  7. Opcional, solo para llaves SWAP: marca Gestionar billeteras (canManageSwapWallets: true en la API del dashboard) para que la llave pueda registrar y eliminar billeteras por API. Reglas:
    • Requiere allowedIps (si faltan: 400 IP_ALLOWLIST_REQUIRED).
    • Solo con scope SWAP (otro scope: 400 INVALID_SCOPE_COMBINATION).
    • Requiere que Mouv habilite la función para tu empresa (403 WALLET_API_NOT_ENABLED).
    • Máximo 2 llaves vigentes con el permiso por empresa (409 WALLET_API_KEY_LIMIT; el body trae activeCount y cap).
    • Las llaves SWAP y las que tienen este permiso se crean con tu código 2FA. La respuesta de creación incluye canManageSwapWallets.
    • Si un administrador marca No la reconozco sobre una billetera registrada por la llave, la llave se revoca.
    Ver Conversión COP→USDT.
  8. La llave plana se muestra una sola vez. Copiala y guardala en tu secret manager — Mouv solo almacena un hash bcrypt, no podemos recuperarla
Si perdés una llave, generá una nueva. Mouv NO puede mostrarte llaves existentes — solo el hash queda almacenado.

Almacenamiento seguro

✅ Recomendado

AWS Secrets Manager · HashiCorp Vault · GCP Secret Manager · environment variables en deploy pipelines

❌ Evitá

Repos públicos · Slack messages · .env committeado · Frontend bundles · Logs sin redacción

Rotación

Recomendamos rotar API keys cada 90 días como mínimo:
  1. Generá una nueva llave con el mismo scope
  2. Actualizá tu sistema a la nueva llave
  3. Verificá que las requests funcionan
  4. Revocá la llave vieja desde el dashboard
Mientras la llave vieja no esté revocada, ambas funcionan en paralelo — usá esto para zero-downtime rotation.

Revocación

Click en Revocar sobre cualquier llave en el dashboard. La revocación es instantánea (cero cache de auth, DB read cada request). Una llave revocada retorna 401 INVALID_API_KEY.

Auditoría

Cada llave tiene:
  • lastUsedAt — actualizado async en cada request exitoso
  • createdAt / createdByUserId — quién la generó
  • revokedAt / revokedByUserId — quién la revocó (si aplica)
  • Audit trail por transacción: el apiKeyId queda persistido en cada Transaction que la llave originó

Modelo multi-tenant

Tu llave solo puede acceder a datos de tu cuenta. Mouv NO tiene endpoints cliente que retornen datos cross-company, y la API key NO puede ser usada para administrar otras cuentas.
Las APIs siguen el patrón Stripe restricted keys:
  • Cada llave tiene un companyId baked-in (no transferible)
  • Todos los queries downstream filtran por companyId automáticamente
  • API keys NO pueden crear otras API keys (anti-privilege-escalation)
  • Si tu cuenta es suspendida, la llave retorna 401 COMPANY_INACTIVE aunque sea válida técnicamente