Autenticación y llaves

Cada solicitud a la API se autentica con una llave en el encabezado Authorization:

Authorization: Bearer aster_test_8KfQ2mVx3TzL9pRw

Las llaves se crean en el portal, en Llaves de API, o con la API (ver Rotar y revocar llaves). El secreto se muestra una sola vez, al crearla. Aster solo guarda un hash, así que no puede recuperarlo: si lo perdés, creá otra llave y revocá la anterior.

Una llave real tiene el prefijo seguido de 40 caracteres alfanuméricos. Los ejemplos de esta documentación son más cortos y ficticios.

Tipos de llave

Tipo	Prefijo	Qué puede hacer	Ambiente de Hacienda
Prueba	aster_test_	Emitir y consultar comprobantes de una organización	Pruebas (staging), o veredicto simulado si la organización no tiene certificado de pruebas
Producción	aster_live_	Emitir y consultar comprobantes de una organización	Producción
Cuenta	aster_test_ / aster_live_ sin organización	Administrar la cuenta: crear organizaciones (emisores) y llaves en /organizations y /api-keys. No emite comprobantes	No aplica

La llave decide el ambiente. No hay un campo environment que elegir: con una llave aster_test_ es imposible emitir un comprobante real por error, y con una aster_live_ todo va a producción. Ver ambientes.

Las llaves de organización solo actúan sobre su organización. Si el issuer.id de un comprobante no es la cédula de esa organización, la API responde 422 organization_mismatch. En una Factura Electrónica de Compra (08) se compara el receiver.id, porque ahí quien emite es el comprador.

Requisitos de las llaves de producción

• La cuenta necesita un plan pagado activo. Sin plan, crear o usar una llave aster_live_ responde 402 plan_required.
• La organización necesita su certificado .p12 de producción, su PIN y sus credenciales de Hacienda. La cédula del certificado tiene que coincidir con la de la organización.

Plataformas con varios emisores

Si tu sistema factura en nombre de varias empresas (un ERP, un punto de venta o un despacho contable), usá una llave de cuenta para crear una organización por emisor con POST /organizations y una llave de prueba y otra de producción por organización con POST /api-keys. Cada organización tiene su certificado, sus credenciales y sus consecutivos. La guía plataformas explica el flujo completo.

Desde una llave de organización, /organizations/me y /organizations/me/certificate leen y actualizan los datos y el certificado de esa organización.

Permisos

Cada llave tiene una lista de permisos (abilities). Por defecto, una llave de organización recibe todos los permisos de la tabla siguiente y una llave de cuenta recibe account:manage. Al crear una llave podés restringirla a menos permisos, por ejemplo una llave de solo lectura para un tablero.

Permiso	Permite
invoices:read	Consultar comprobantes y facturas
invoices:write	Crear y actualizar facturas
invoices:sign	Firmar y enviar comprobantes a Hacienda, y enviar Mensajes Receptor
invoices:void	Anular comprobantes
credit-notes:read	Consultar notas de crédito
credit-notes:write	Crear y actualizar notas de crédito
credit-notes:sign	Firmar y enviar notas de crédito
debit-notes:read	Consultar notas de débito
debit-notes:write	Crear y actualizar notas de débito
debit-notes:sign	Firmar y enviar notas de débito
tickets:read	Consultar tiquetes
tickets:write	Crear y actualizar tiquetes
tickets:sign	Firmar y enviar tiquetes
recipients:read	Consultar receptores guardados
recipients:write	Crear y actualizar receptores
hacienda:query	Consultar el estado de Hacienda y de un comprobante en Hacienda
hacienda:validate	Validar un comprobante sin enviarlo
settings:read	Ver los datos de la organización y el estado del certificado
settings:manage	Cambiar los datos de la organización y subir certificados
webhooks:read	Ver webhooks
webhooks:write	Crear webhooks
webhooks:manage	Modificar, probar y eliminar webhooks
reference:read	Consultar tipos de cambio
documents:export	Descargar los XML en un ZIP
account:manage	Administrar organizaciones y llaves (solo llaves de cuenta)

Emitir un comprobante con POST /electronic-documents requiere invoices:write e invoices:sign. Una llave sin el permiso que pide el endpoint recibe 403 forbidden. La lista completa con descripciones está en GET /auth/scopes, que no requiere autenticación.

Rotar y revocar llaves

Con una llave de cuenta podés administrar las llaves por API:

Método	Ruta	Uso
GET	/api-keys	Lista las llaves de la cuenta, incluidas las revocadas, sin el secreto
POST	/api-keys	Crea una llave y devuelve el secreto una sola vez
DELETE	/api-keys/{id}	Revoca una llave de inmediato

Crear una llave de prueba para una organización

curl https://aster.astranexo.com/api/v1/api-keys \
  -H "Authorization: Bearer $ASTER_ACCOUNT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "POS tienda Guadalupe",
    "mode": "test",
    "organization_id": "7c0e5b52-3f4d-4a8e-9a51-2b6f0e9d1c47",
    "abilities": ["invoices:read", "invoices:write", "invoices:sign"]
  }'

201 Created

{
  "success": true,
  "message": "API key created. Store the secret now: it isn't shown again.",
  "data": {
    "id": "e3a9c1d2-5b7f-4f0a-8c6e-1d2b3a4c5e6f",
    "mode": "test",
    "name": "POS tienda Guadalupe",
    "prefix": "aster_test_8KfQ2mVx",
    "abilities": ["invoices:read", "invoices:write", "invoices:sign"],
    "last_used_at": null,
    "expires_at": null,
    "revoked_at": null,
    "created_at": "2026-10-08T16:05:42Z",
    "organization_id": "7c0e5b52-3f4d-4a8e-9a51-2b6f0e9d1c47",
    "secret": "aster_test_8KfQ2mVx3TzL9pRw"
  }
}

Campos de POST /api-keys:

Campo	Tipo	Requerido	Descripción
name	string	Sí	Nombre para reconocerla, máximo 100 caracteres
mode	string	Sí	test o live
organization_id	string	No	Organización a la que pertenece la llave
abilities	string[]	No	Permisos. Si se omite, recibe todos los que corresponden a su tipo
expires_at	string	No	Fecha de vencimiento RFC 3339. Si se omite, no vence

Para rotar una llave sin cortar el servicio: creá la nueva, desplegala en tu servidor, verificá en GET /api-keys que la nueva tiene last_used_at reciente y después revocá la anterior con DELETE /api-keys/{id}. Una llave no puede revocarse a sí misma (422 cannot_revoke_current_key). Una llave revocada responde 401 key_revoked desde ese momento.

Tokens heredados

Los tokens con formato {id}|{token} que se obtienen con POST /auth/token (correo y contraseña) siguen funcionando con el mismo encabezado Authorization: Bearer. Con esos tokens el ambiente se elige con el campo environment (staging o production) de cada solicitud. Para integraciones nuevas usá llaves aster_test_ y aster_live_.

Buenas prácticas

• Usá las llaves solo en tu servidor. La API acepta llamadas desde navegadores únicamente de los orígenes de Aster (el portal y la referencia interactiva), así que una app web o móvil no puede llamar la API directamente con una llave. Hacé las llamadas desde tu backend.
• Guardalas fuera del código, en variables de entorno o en un gestor de secretos. No las subas a un repositorio.
• Una llave por integración (por ejemplo, una por punto de venta o por servicio). Así podés revocar una sin afectar las demás y ver en last_used_at cuál se usa.
• Pedí solo los permisos necesarios. Un tablero de reportes no necesita invoices:sign.
• Si una llave se filtra, revocala de inmediato y creá otra. Revisá en el portal los comprobantes emitidos con ella.
• Las respuestas con error de autenticación (401, 402, 403) usan el formato de errores de siempre, con un error.code estable que podés manejar en código.