Autenticación

Bearer token

Manda tu key en el header Authorization con el esquema Bearer en cada petición. Nunca la pongas en la URL ni en el cuerpo, y nunca la expongas en código de cliente.

Authorization: Bearer allsign_{env}_sk_...

curl https://api.allsign.io/v3/documents \
  -H "Authorization: Bearer allsign_test_sk_..."

Prefijos de key

El prefijo de la key te dice, a simple vista, en qué entorno estás operando. El segmento {env} es test (sandbox) o live (producción):

sk = secret key: es un secreto de servidor. Trátala como una contraseña, rótala si se filtra, y no la subas al repositorio.

Scopes por recurso

Los scopes tienen la forma recurso:acción. Una key solo puede hacer lo que sus scopes permiten. La taxonomía está congelada y es append-only: nunca renombramos ni quitamos un scope; solo agregamos nuevos. Así, un cliente que programa contra un scope no se rompe.

Existen wildcards para conveniencia:

• recurso:* — todas las acciones sobre un recurso (p.ej. document:* = read + write + delete).
• * — acceso total (úsalo con extremo cuidado; prefiere el mínimo privilegio).

Sin key: 401

Si no mandas key, o la key es inválida o revocada, la API responde 401 AUTHENTICATION_REQUIRED y agrega el header estándar WWW-Authenticate: Bearer. Esto significa "autentícate", no "no tienes permiso".

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
Content-Type: application/problem+json

{
  "type": "https://developers.allsign.io/errors#AUTHENTICATION_REQUIRED",
  "title": "Authentication required",
  "status": 401,
  "code": "AUTHENTICATION_REQUIRED",
  "detail": "Provide an API key via Authorization: Bearer allsign_live_sk_…",
  "requestId": "req_..."
}

Sin scope: 403 con requiredScope

Si tu key es válida pero le falta el scope que el endpoint exige, obtienes 403 PERMISSION_DENIED. El error te dice exactamente qué scope necesitas (requiredScope) y cuáles tiene tu key (yourScopes), para que corrijas sin adivinar.

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json

{
  "type": "https://developers.allsign.io/errors#PERMISSION_DENIED",
  "title": "Permission denied",
  "status": 403,
  "code": "PERMISSION_DENIED",
  "detail": "This API key is missing the 'document:write' scope.",
  "requiredScope": "document:write",
  "yourScopes": ["document:read", "user:read"],
  "requestId": "req_..."
}

GET /v3/users/me es la excepción: nunca responde 403. Cualquier key autenticada puede leer su propio usuario, sin importar sus scopes — úsalo como health check de autenticación.

OAuth 2.1 (próximamente)

Hoy la única forma de autenticarse es la API key (bearer). OAuth 2.1 (para apps de terceros que actúan en nombre de un usuario) está en el roadmap pero aún no está implementado. Si presentas un token OAuth (con forma de JWT) como bearer en cualquier endpoint v3, la API responde 501 OAUTH_NOT_IMPLEMENTED, para que tu integración distinga "todavía no existe" de "salió mal".

HTTP/1.1 501 Not Implemented
Content-Type: application/problem+json

{
  "type": "https://developers.allsign.io/errors#OAUTH_NOT_IMPLEMENTED",
  "title": "Not Implemented",
  "status": 501,
  "code": "OAUTH_NOT_IMPLEMENTED",
  "detail": "This credential looks like an OAuth token. AllSign v3 currently accepts API keys only (Authorization: Bearer allsign_live_sk_…). OAuth (Ory Hydra) is a fast-follow; see https://developers.allsign.io/authentication.",
  "requestId": "req_..."
}

Formato de error (problem+json)

Todo error de autenticación (y todo error de la API) es un documento RFC 9457 application/problem+json. Ramifica tu lógica por el campo code (estable, append-only), nunca por detail (texto en inglés que puede cambiar) ni por el title.

Headers en cada respuesta

AllSign-Request-Id viaja en toda respuesta. Los headers de entorno y rate limiting viajan en toda respuesta autenticada (incluidos 403 y 429) — un 401 sin credenciales no los trae: