# API environments and keys

> Create live or test API keys, choose scopes, and find the base URL of the Alya Books API.

Source: /help/en/api/environments-and-api-keys

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

1. Go to **API access** (System group in the sidebar) → **API keys** tab → **New key**.
2. Give it a name you will recognise, such as the system that uses it.
3. Switch on **Test key** if the documents it creates should be marked as test.
4. Optionally set an expiry date.
5. Choose the scopes. **all** and **read-only** are shortcuts.
6. 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](/help/en/api/connect-ai-assistants).

## Related

- [Why do I get 401 on API calls?](/help/en/api/401-troubleshooting)
- [API errors and status codes](/help/en/api/error-handling)