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)	`allsign_live_sk_...`
token	Cadena aleatoria segura	`abc123xyz789...`

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

Autenticación

Solo necesitas tu API key en el header Authorization. Así de simple:

Ejemplo

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

Tu API key ya identifica al usuario y al workspace. No necesitas enviar ningún otro header de autenticación.

No envíes headers adicionales de autenticación. Si solo tienes un workspace (la mayoría de integraciones), Authorization: Bearer es todo lo que necesitas. Headers como X-User-Id o X-On-Behalf-Of enviados vacíos o sin configuración causarán errores 401/403.

Avanzado: Autenticación multi-tenant

Estos modos son solo para plataformas que manejan múltiples usuarios o workspaces. Si manejas un solo workspace, ignora esta sección.

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:

Ejemplo

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

Acceso delegado (X-On-Behalf-Of)

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

Ejemplo

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

Ambos headers requieren que tu API key tenga permisos de impersonación habilitados. Contacta soporte para activarlos.

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": {
    "error_code": "INSUFFICIENT_SCOPE",
    "message": "Insufficient permissions.",
    "required_scopes": ["document:write", "document:*"],
    "your_scopes": ["document:read"],
    "hint": "Add 'document:write' or 'document:*' to this API key in the AllSign dashboard under Developers → API Keys."
  }
}

Los headers X-Accepted-Scopes y X-Your-Scopes también están presentes en la respuesta para diagnóstico rápido sin parsear el body.

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

El límite de peticiones por minuto está determinado por tu plan de suscripción activo (default: 100 req/min). El límite aplica igual para keys dev, test y live del mismo tenant.

Exceder el límite devuelve 429 Too Many Requests con el header Retry-After. Ver Rate Limits para detalles.

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
✅ Si usas multi-tenant, usa UUIDs en lugar de emails para identificar usuarios