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` (trial/pruebas), `dev` (sandbox)	`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. Los headers X-User-Id y X-On-Behalf-Of enviados vacíos se ignoran (la petición procede en modo estándar). Un X-User-Id con un UUID inexistente devuelve 400 Bad Request; un X-On-Behalf-Of sin el scope de delegación devuelve 403 INSUFFICIENT_DELEGATION_SCOPE.

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 actuar como un usuario de tu mismo tenant:

Ejemplo

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

El usuario objetivo debe pertenecer al mismo tenant que el dueño del API key. El scope user-context:app-mode activa el modo app (que impone requisitos adicionales en algunos endpoints, p.ej. permissions.ownerEmail al crear documentos).

Acceso delegado (X-On-Behalf-Of)

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

Ejemplo

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

X-On-Behalf-Of requiere que tu API key tenga el scope de delegación (delegation:impersonate, delegation:* o *); sin él recibes 403 INSUFFICIENT_DELEGATION_SCOPE. Para X-User-Id, agrega el scope user-context:app-mode a tu key para habilitar el modo app.

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

Firma embebida (iframe)

embedded:write — Crear sesiones de firma embebida (requerido por POST /v2/signing-sessions, junto con document:write o document:*)

Analítica

analytics:read — Leer datos de analítica y uso (requerido por los endpoints /v2/analytics)

Avanzado

user-context:app-mode — Actuar como otro usuario vía X-User-Id (modo app)
delegation:impersonate — Actuar en nombre de firmantes externos vía X-On-Behalf-Of
webhook:read, webhook:write — Leer y administrar webhooks
* — Acceso administrativo total

Los scopes no siempre coinciden con el recurso "obvio": los endpoints de Usuarios (/v2/users/me, /v2/users/team) requieren document:read (o document:*), no user:read. Crea tus keys con document:read para acceder al perfil del usuario.

Si tu API key no tiene el scope necesario, recibirás 403 Forbidden. El cuerpo del error usa el envelope estándar de la API (clave raíz error, no detail):

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "type": "permission_error",
    "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.",
    "documentation_url": "https://developers.allsign.io/authentication"
  }
}

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

Hay dos capas de límite y aplica la más restrictiva:

Por tenant — determinado por tu plan de suscripción activo (default: 100 req/min). Aplica igual para keys dev, test y live del mismo tenant.
Por endpoint — caps fijos para operaciones costosas que pueden ser menores que tu plan: crear documento 20/min, invitación masiva (invite-bulk) 10/min, invitación individual (invite) 30/min.

El header X-RateLimit-Reason indica qué capa disparó el 429 (per-tenant vs endpoint). Exceder el límite devuelve 429 Too Many Requests con el header Retry-After. Ver Rate Limits para detalles.

Aislamiento por ambiente

Cada documento queda estampado con el ambiente (live/test/dev) de la key que lo creó. En los listados (GET /v2/documents) el filtro por defecto es el ambiente de tu key; puedes ver todo con ?environment=all. Las lecturas por ID (GET /v2/documents/{id}) son tenant-scoped y no filtran por ambiente.

El aislamiento por ambiente es un filtro de conveniencia, no una barrera de seguridad: una key test/dev del mismo tenant puede acceder a recursos live. No uses ambientes como frontera de aislamiento de datos sensibles; el verdadero límite de seguridad es el tenant.

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 un key comprometido (efectivo en menos de ~60 segundos por el cache de autenticación)

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