Conceptos

Autenticación

La API se autentica con Bearer tokens emitidos desde el dashboard. No usamos cookies ni sesiones; toda petición es independiente.

Tipos de key

Cada tenant puede crear dos clases de key:

  • fwk_live_* — emite ante SUNAT producción. Consume tu cuota mensual y afecta tu facturación.
  • fwk_test_* — emite ante homologación SUNAT (sandbox). No consume cuota ni cobra. Útil para CI y desarrollo.
Anatomía del token
fwk_live_K7H9M3J2N4P5Q6R8S1T0U2V3W4X5Y6Z7
└──┬──┘└┬┘└────────────────┬────────────────┘
   │    │                  │
   │    │                  └─ 32 caracteres base32 (entropía 160 bits)
   │    └─ environment: 'live' o 'test'
   └─ prefijo Fiscal-Web ("fwk" = Fiscal-Web Key)

Solo guardamos hash

El token completo (40 caracteres) se ve UNA vez al crear la key. En base de datos guardamos solo bcrypt(token) con cost 12 — si pierdes el token, no podemos recuperarlo, tienes que rotar.

Cómo enviar la key

En cada petición, header HTTP Authorization con prefijo Bearer :

Authorization header
curl -H "Authorization: Bearer fwk_live_<32-chars>" \
     https://api.fiscal-web.pe/v1/documents

Nunca en query string. Nunca en path. Ambos quedan en logs de proxies y CDNs.

Scopes

Cada key se crea con un subconjunto de scopes (principio de menor privilegio). Lista canónica:

  • documents:read — listar y leer documentos.
  • documents:write — emitir documentos nuevos.
  • documents:cancel — anular documentos emitidos.
  • credentials:read — leer metadata de credenciales (NO contenido).
  • webhooks:read — leer endpoints + deliveries.
  • webhooks:write — crear, rotar y replayar deliveries.

Cuando una key tiene documents:read pero llama un endpoint que requiere documents:write, la respuesta es 403 Forbidden con código insufficient_scope.

Rotación y revocación

En /app/keys puedes:

  • Rotar — genera un nuevo token y mantiene la key vieja activa N días (configurable, default 7). Útil para rolling deployments.
  • Revocar — invalida la key inmediatamente. Toda petición con esa key recibe 401 a partir de ese momento.

Si sospechas que una key se filtró, revoca primero, investiga después.

Qué no hacer

  • Frontend: nunca uses la API key desde el navegador. Hazlo siempre desde tu backend.
  • Commits: nunca commitees keys. Si te pasa, revoca y rota. Nuestro detector de keys en logs alerta cuando un token aparece en outputs.
  • Compartir: cada developer debería tener su propia fwk_test_*. Las fwk_live_* solo en CI/producción.