Getting started with Alunta's public API

Historical retrospective - November 2025
This article was written afterwards and describes API access as it was introduced during the period.

The API connects Alunta with a system you operate. Use it to read team data and for the actions allowed by the current v1 contract. The public API reference and OpenAPI document are authoritative for fields, statuses, and responses.

Before the first request

Enable the API module for the team and go to Settings → API. Create a personal API token by entering a name, then copy the token when it is shown. A token is a secret: store it in a secret manager or environment variable, never in source code, a URL, logs, or a support example. Use a separate test account while developing the integration. Partner integrations may have a separate OAuth authorization flow; that is different from the team’s personal API token.

The v1 base is /api/v1. A minimal request looks like this:

GET /api/v1/customers
Authorization: Bearer {access-token}
Accept: application/json

Store the UUIDs returned by the API and use them for later lookups. Internal database IDs are not public references and must not be used as stable keys.

Read the contract first

Open the public API reference or OpenAPI specification before building a request. Check the resource’s fields, pagination, validation, and response. API amounts use the smallest currency unit where the contract says so; for example, 10000 DKK normally means DKK 100.00.

401 usually means a missing or expired token. 403 means insufficient permission or an API module unavailable to the team. For 422, read field errors and correct the request. Honour Retry-After after 429, and retry only operations that are safe to repeat.

Once the integration is running

Use pagination as documented for each endpoint and do not assume every collection accepts the same filters. Use webhooks for events instead of unnecessary polling, and make the receiver idempotent. Keep the client aligned with the public changelog and contract documentation.

You can revoke a personal token at any time under Settings → API. This stops requests using that token; create a new token and update the integration’s secret if the connection should continue.

See the current public API and webhooks guide (Markdown file, AI agent-friendly) for a complete workflow and troubleshooting.

A safe first workflow

Start with GET /api/v1/ping or GET /api/v1/me when those endpoints are available to the token, then continue with GET /api/v1/customers. Store response status and a request identifier in your integration, but never the token. When a collection has multiple pages, follow the pagination documented for that endpoint and stop only when there is no next page.

A test using the fictional, nonexistent customer UUID 00000000-0000-4000-8000-000000000001 should handle both 404 and 422 without automatically creating a new customer. 404 means the resource does not exist in the token’s team context. 422 means the data or action is invalid. Show the difference in your admin interface so a user knows whether to fix access or input.

Can one token be used for every team? No. Access is tied to the team context. Select the correct account and create suitable access.

Is a UUID the same as an external ID? No. The UUID is Alunta’s reference; an optional external ID is your system’s mapping.

Should every 5xx be retried? Use bounded retries for network errors and temporary 5xx responses, but do not blindly retry an action that could create a new resource.