Autenticación

FactuLink ofrece dos métodos de autenticación para acceder a la API. Elige el que mejor se adapte a tu caso de uso.

API Keys (recomendado para server-to-server)

Las API Keys son la forma más sencilla de autenticarte. Son ideales para backends e integraciones donde no hay un usuario interactivo.

Formato de las keys

• sk_live_ — Producción (timbrado real contra el SAT)
• sk_test_ — Sandbox (timbrado simulado, sin envío al SAT)

El prefijo determina automáticamente el ambiente. No necesitas configurar nada adicional.

Crear una API Key

Para crear una API Key necesitas un JWT con rol ADMIN:

{
"name": "Backend de facturación",
"scopes": ["cfdis:read", "cfdis:write", "clients:read"],
"environment": "test"
}

{
"id": "key_01J5K...",
"name": "Backend de facturación",
"prefix": "sk_test_",
"key": "sk_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
"scopes": ["cfdis:read", "cfdis:write", "clients:read"],
"environment": "test",
"created_at": "2026-04-05T10:30:00Z"
}

Importante: La key completa se muestra una sola vez al momento de crearla. Guárdala en un lugar seguro. Después solo verás el prefijo.

Uso en peticiones

Envía la API Key en el header Authorization con el esquema Bearer:

curl -X GET https://api.factulink.com.mx/api/v1/cfdis \
-H "Authorization: Bearer sk_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
-H "Content-Type: application/json"

JWT (para frontend / browser)

Si estás construyendo una aplicación con usuarios interactivos, usa JWT. El flujo es: login con email/password, obtener tokens, y usarlos para autenticar peticiones.

Login

{
"email": "admin@empresa.com",
"password": "tu-password-seguro"
}

{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"refresh_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 86400,
"user": {
  "id": "usr_01J5K...",
  "email": "admin@empresa.com",
  "role": "ADMIN",
  "organization_id": "org_01J5K..."
}
}

Refresh Token

Cuando el access_token expire (24 horas), usa el refresh_token para obtener uno nuevo sin pedir credenciales de nuevo:

{
"refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"refresh_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 86400
}

Duración de tokens

Si el refresh_token también expira, el usuario debe iniciar sesión de nuevo.

Scopes (permisos por API Key)

Cada API Key puede tener un conjunto de scopes que limitan qué operaciones puede realizar. Usa siempre los scopes mínimos necesarios.

Buenas prácticas

• Nunca expongas API Keys en código frontend. Las keys sk_live_ y sk_test_ son secretas. Úsalas solo en backends.
• Usa variables de entorno. Almacena las keys en FC_API_KEY o equivalente, nunca las hardcodees en el código.
• Rota keys periódicamente. Puedes tener múltiples keys activas para facilitar la rotación sin downtime.
• Usa los scopes mínimos necesarios. Si tu integración solo lee CFDIs, no le des cfdis:write ni cfdis:cancel.
• Maneja la expiración de JWT. Implementa lógica de refresh automático en tu cliente para evitar interrupciones.