Authentication and keys

Every API request is authenticated with a key in the Authorization header:

Authorization: Bearer aster_test_8KfQ2mVx3TzL9pRw

Keys are created in the dashboard, under Llaves de API (API keys), or through the API (see Rotating and revoking keys). The secret is shown only once, when the key is created. Aster stores only a hash, so it cannot recover it: if you lose it, create a new key and revoke the old one.

A real key is the prefix followed by 40 alphanumeric characters. The examples in this documentation are shorter and fictitious.

Key types

Type	Prefix	What it can do	Hacienda environment
Test	aster_test_	Issue and read documents for one organization	Test (staging), or a simulated verdict when the organization has no test certificate
Live	aster_live_	Issue and read documents for one organization	Production
Account	aster_test_ / aster_live_ without an organization	Manage the account: create organizations (issuers) and keys with /organizations and /api-keys. Does not issue documents	Not applicable

The key decides the environment. There is no environment field to choose: with an aster_test_ key you cannot issue a real document by mistake, and with an aster_live_ key everything goes to production. See Ambientes (in Spanish).

Organization keys only act on their own organization. If a document’s issuer.id is not that organization’s ID, the API answers 422 organization_mismatch. On a Factura Electrónica de Compra (08) the receiver.id is compared instead, because the buyer is the one issuing it.

Requirements for live keys

• The account needs an active paid plan. Without one, creating or using an aster_live_ key answers 402 plan_required.
• The organization needs its production .p12 certificate, its PIN and its Hacienda credentials. The certificate’s ID must match the organization’s.

Platforms with several issuers

If your system invoices on behalf of several companies (an ERP, a point of sale or an accounting firm), use an account key to create one organization per issuer with POST /organizations, and one test and one live key per organization with POST /api-keys. Each organization has its own certificate, credentials and consecutivos. The Plataformas guide (in Spanish) walks through the full flow.

From an organization key, /organizations/me and /organizations/me/certificate read and update that organization’s data and certificate.

Permissions

Each key has a list of permissions (abilities). By default an organization key gets every permission in the table below and an account key gets account:manage. When you create a key you can restrict it, for example a read-only key for a dashboard.

Permission	Allows
invoices:read	Read documents and invoices
invoices:write	Create and update invoices
invoices:sign	Sign and send documents to Hacienda, and send receptor messages
invoices:void	Void documents
credit-notes:read	Read credit notes
credit-notes:write	Create and update credit notes
credit-notes:sign	Sign and send credit notes
debit-notes:read	Read debit notes
debit-notes:write	Create and update debit notes
debit-notes:sign	Sign and send debit notes
tickets:read	Read tickets
tickets:write	Create and update tickets
tickets:sign	Sign and send tickets
recipients:read	Read saved recipients
recipients:write	Create and update recipients
hacienda:query	Check Hacienda’s status and a document’s status at Hacienda
hacienda:validate	Validate a document without sending it
settings:read	Read the organization’s data and certificate status
settings:manage	Change the organization’s data and upload certificates
webhooks:read	Read webhooks
webhooks:write	Create webhooks
webhooks:manage	Update, test and delete webhooks
reference:read	Read exchange rates
documents:export	Download XML files as a ZIP
account:manage	Manage organizations and keys (account keys only)

Issuing a document with POST /electronic-documents requires invoices:write and invoices:sign. A key without the permission an endpoint needs gets 403 forbidden. The full list with descriptions is at GET /auth/scopes, which needs no authentication.

Rotating and revoking keys

With an account key you can manage keys through the API:

Method	Path	Use
GET	/api-keys	Lists the account’s keys, revoked ones included, without secrets
POST	/api-keys	Creates a key and returns the secret once
DELETE	/api-keys/{id}	Revokes a key immediately

Create a test key for an organization

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"
  }
}

POST /api-keys fields:

Field	Type	Required	Description
name	string	Yes	A name to recognize it, at most 100 characters
mode	string	Yes	test or live
organization_id	string	No	Organization the key belongs to
abilities	string[]	No	Permissions. If omitted, the key gets every permission for its type
expires_at	string	No	RFC 3339 expiry. If omitted, the key never expires

To rotate a key without downtime: create the new key, deploy it to your server, confirm in GET /api-keys that the new key shows a recent last_used_at, then revoke the old one with DELETE /api-keys/{id}. A key cannot revoke itself (422 cannot_revoke_current_key). A revoked key answers 401 key_revoked from then on.

Legacy tokens

Tokens in the {id}|{token} format, obtained with POST /auth/token (email and password), keep working with the same Authorization: Bearer header. With those tokens the environment is chosen with each request’s environment field (staging or production). For new integrations, use aster_test_ and aster_live_ keys.

Good practices

• Use keys on your server only. The API accepts browser calls only from Aster’s own origins (the dashboard and the interactive reference), so a web or mobile app cannot call the API directly with a key. Make the calls from your backend.
• Keep keys out of your code, in environment variables or a secrets manager. Never commit them to a repository.
• One key per integration (for example, one per point of sale or per service). That way you can revoke one without affecting the others, and last_used_at shows which one is in use.
• Grant only the permissions you need. A reporting dashboard doesn’t need invoices:sign.
• If a key leaks, revoke it immediately and create another. Review the documents issued with it in the dashboard.
• Authentication errors (401, 402, 403) use the usual error format, with a stable error.code you can handle in code.