API environments and keys
Create live or test API keys, choose scopes, and find the base URL of the Alya Books API.
The Alya Books REST API lets your ERP, shop or accounting tool create invoices, import received ones and receive webhooks. Access is controlled with API keys that you manage in the app.
Create a key
- Go to API access (System group in the sidebar) → API keys tab → New key.
- Give it a name you will recognise, such as the system that uses it.
- Switch on Test key if the documents it creates should be marked as test.
- Optionally set an expiry date.
- Choose the scopes. all and read-only are shortcuts.
- Click Create key and copy the key from the next dialog. It is shown only once; Alya Books stores a hash.
Live and test
| Key | Prefix | Effect |
|---|---|---|
| Live | sk_live_… | Creates real documents that follow your Settings → E-invoicing mode |
| Test | sk_test_… | Creates documents with the test flag; they never reach the live ASP and are excluded from reports. Listing with a test key returns only test documents. |
The test key is Alya Books's demo environment; there is no separate sandbox URL.
Every key starts with sk_live_ or sk_test_, so you can tell the environment from the key itself. Integrations that check the key format should accept these prefixes.
Scopes
Invoices, Incoming invoices, Customers, Products, Custom fields and Number series each have read and write; write includes read. Webhooks have a single manage scope. A request outside the key's scopes gets 403 FORBIDDEN naming the missing scope.
Base URL and first call
The Endpoint card on the API access page shows the base URL for your environment (https://api.alyabooks.ai/api/v1 once the custom domain is live) and a copyable example:
curl <base>/me -H "X-API-KEY: sk_live_…"
GET /me returns your organization, the key's scopes and its environment.
Good to know
- Owners and admins manage keys. Other members need the "manage API keys" permission under Settings → Team → Permissions.
- The keys table shows the prefix, scope count, last use with the number of calls, and the status active, expired or revoked. Revoke stops a key immediately and keeps it listed; Delete removes it.
- CA firms send
X-Organization-Id: <client org id>to act for a managed client. - Limit: 600 requests per minute per key.
- The Recent requests tab logs calls for troubleshooting. The OpenAPI specification is linked from the same page.
- Connected apps: Claude, ChatGPT and other AI assistants can connect by signing in instead of using a key. They are listed, with their permissions, in the Connected apps card under the API keys tab, where Revoke stops them. See Connect Alya Books to Claude or ChatGPT.