Autenticación

La API de Folyo soporta dos métodos de autenticación.

JWT Bearer Token

Obtén un token haciendo login con email y password:

http
POST https://api.folyo.cl/auth/login
Content-Type: application/json

{ "email": "tu@empresa.cl", "password": "tu_password" }

La respuesta incluye access_token (válido 1 hora) y refresh_token (válido 7 días). Úsalos así:

http
Authorization: Bearer <access_token>

Cuando el access_token expire, renuévalo con POST /auth/refresh.

API Key

Crea una API Key desde el dashboard en API Keys. Es ideal para integraciones server-to-server.

http
X-API-Key: <api_key>

Al crearla puedes darle una fecha de expiración (opcional: sin expires_at la key no expira). Una key vencida recibe 401 con código API_KEY_EXPIRED, distinto del UNAUTHORIZED de una key inválida o revocada, para que tu integración pueda distinguir ambos casos. La expiración no se puede extender: para renovar, crea una key de reemplazo desde el panel y actualiza tu sistema. Avisamos por correo y en el centro de notificaciones 7 días antes del vencimiento.

Multi-empresa

La empresa emisora no se elige por request: sale de la credencial con la que llamas.

Con API Key. Cada key queda ligada a una empresa cuando la creas en el dashboard. Todas las peticiones que hagas con esa key operan sobre esa empresa. Si administras varias, crea una key por empresa y usa la que corresponda. Las keys antiguas creadas sin empresa asociada caen a la empresa más antigua de la cuenta: si estás en ese caso, créalas de nuevo indicando la empresa.

Con JWT. El token lleva la empresa activa de la sesión. Para cambiarla:

http
POST https://api.folyo.cl/v1/empresa/seleccionar
Authorization: Bearer <access_token>
Content-Type: application/json

{ "empresa_id": "<empresa_id>" }

La respuesta trae un par de tokens nuevo, ya apuntando a esa empresa.

Roles

Las operaciones sobre credenciales y configuración del emisor (certificado digital, clave SII, datos de la empresa, folios, API keys, webhooks) exigen rol owner o admin, y responden 403 ROLE_FORBIDDEN al resto. Crear y revocar API keys, además, solo funciona con sesión de usuario: con X-API-Key responden 403 JWT_REQUERIDO.

Seguridad

  • Nunca expongas tu API Key en código del lado del cliente (browser)
  • Rota las API Keys periódicamente desde el dashboard
  • Al hacer logout el token queda invalidado, aunque no haya expirado