Autenticación

Toda petición a la API necesita un API key válido. AllSign usa Bearer token authentication — agrega tu API key en el header Authorization y listo.

Lo básico en 30 segundos

curl https://api.allsign.io/v2/documents \
  -H "Authorization: Bearer allsign_live_sk_TU_API_KEY"

Eso es todo. El Bearer + tu API key en cada petición.

Formato del API key

Los API keys de AllSign tienen un formato predecible:

allsign_{ambiente}_{tipo}_{token}

Parte	Valores	Ejemplo
ambiente	`live` (producción), `test` (desarrollo)	`allsign_live_...`
tipo	`sk` (server key), `user_sk` (usuario)	`allsign_live_sk_...`
token	Cadena aleatoria segura	`abc123xyz789...`

Nunca subas API keys a tu repositorio. Usa variables de entorno o un gestor de secretos.

¿Qué modo de autenticación necesito?

Escenario	Modo	Header
App de un solo usuario	API key de usuario	`Authorization: Bearer allsign_live_user_sk_xxx`
App multi-usuario / plataforma	API key de app + usuario	`Authorization: Bearer allsign_live_sk_xxx` + `X-User-Id: {uuid}`
Soporte actuando por un cliente	Acceso delegado	`Authorization: Bearer allsign_live_sk_xxx` + `X-On-Behalf-Of: email@cliente.com`

Modo 1: API key de usuario

El más simple. Tu API key ya identifica al usuario:

Ideal para aplicaciones de un solo usuario o cuando cada usuario tiene su propio API key.

Ejemplo

curl https://api.allsign.io/v2/documents \
  -H "Authorization: Bearer allsign_live_user_sk_abc123"

Modo 2: API key de app + X-User-Id

Para plataformas multi-usuario. Un solo API key de app + el header X-User-Id para especificar el usuario:

Ideal para integraciones, plataformas SaaS o cuando necesitas operar en nombre de distintos usuarios con una sola credencial.

Ejemplo

curl https://api.allsign.io/v2/documents \
  -H "Authorization: Bearer allsign_live_sk_xyz789" \
  -H "X-User-Id: 550e8400-e29b-41d4-a716-446655440000"

JavaScript

const response = await fetch('https://api.allsign.io/v2/documents', {
  headers: {
    'Authorization': 'Bearer allsign_live_sk_xyz789',
    'X-User-Id': '550e8400-e29b-41d4-a716-446655440000',
    'Content-Type': 'application/json'
  }
});

Modo 3: Acceso delegado

Para equipos de soporte o administradores que necesitan actuar en nombre de un cliente:

Usa X-On-Behalf-Of con el email del usuario final. Los logs de auditoría registran tanto tu cuenta como la del usuario beneficiado.

Casos de uso:

Soporte técnico reenvía un documento sin pedir el API key del cliente
Tu plataforma automatiza acciones transparentes para el usuario final

Ejemplo

curl https://api.allsign.io/v2/documents \
  -H "Authorization: Bearer allsign_live_sk_xyz789" \
  -H "X-On-Behalf-Of: cliente@empresa.com"

Scopes y permisos

Cada API key tiene permisos granulares que definen qué puede hacer:

Documentos

document:read — Listar y ver documentos
document:write — Crear y actualizar documentos
document:delete — Eliminar documentos
document:* — Todas las operaciones de documentos

Firmas

signature:read — Ver firmas
signature:write — Crear y actualizar firmas
signature:* — Todas las operaciones de firmas

Si tu API key no tiene el scope necesario, recibirás 403 Forbidden:

{
  "detail": "Insufficient permissions. Required: document:write or document:*. Your scopes: document:read"
}

Seguridad avanzada

IP allowlists

Restringe tu API key a IPs específicas. Peticiones desde IPs no autorizadas se rechazan automáticamente:

{
  "allowed_ips": [
    "203.0.113.42",
    "198.51.100.0/24"
  ]
}

Rate limiting

Límites por plan para prevenir abuso:

Plan	Peticiones/minuto	Peticiones/hora
Starter	60	1,000
Professional	120	5,000
Enterprise	300	15,000

Exceder el límite devuelve 429 Too Many Requests con el header Retry-After.

Aislamiento por ambiente

API keys live solo acceden a datos de producción
API keys test solo acceden a datos de prueba

No hay forma de mezclar datos accidentalmente.

Gestionar API keys

Desde el Dashboard de AllSign:

Crear — Selecciona scopes y opcionalmente configura IP allowlists
Copiar — El API key completo solo se muestra al crearlo
Revocar — Invalida inmediatamente un key comprometido

Guarda tu API key inmediatamente después de crearlo. Por seguridad, el key completo no se puede recuperar después — solo se muestran los últimos 4 caracteres.

Buenas prácticas

✅ Usa variables de entorno — nunca hardcodees API keys en tu código
✅ Mínimos permisos — crea keys solo con los scopes que necesitas
✅ Keys separados por ambiente (desarrollo, staging, producción)
✅ Rota keys regularmente — cada 90 días es buena práctica
✅ IP allowlists para servidores con IPs fijas
✅ Revoca inmediatamente cualquier key que sospechas comprometido
✅ Usa user_id (UUID) en lugar de emails para identificar usuarios en X-User-Id