API keys & permissions

Create an API key

1. Open API-nøkler in Aventra. You must be a workspace administrator.
2. Create a key with a recognisable name, such as Website lead intake.
3. Choose permissions for companies, contacts, offers and tasks.
4. Copy the key when it is shown and save it in your server's secret store. You cannot reveal it again.

For the lead intake walkthrough, choose read and write for companies, contacts and tasks. Offers can stay at no access.

Authenticate a request

Every API request needs an Authorization header. The base URL includes /api/v1.

export AVENTRA_API_KEY='your-api-key'

curl https://api.aventra.no/api/v1/me \
  -H "Authorization: Bearer $AVENTRA_API_KEY"

{
  "data": {
    "tenant_id": "3c47421c-3113-4206-bec8-e779c29932bc",
    "user_id": "f52b3fd3-5ff4-4d93-91c5-6ac79e21cdd5",
    "permissions": 207
  }
}

The workspace comes from the API key. Do not send tenant_id or customer_id in write requests: these fields are rejected. The returned user_id identifies the key creator. To choose an assignee or offer owner, use GET users to resolve a workspace member by email. Task and offer creation both require user_id.

Choose permissions

Adding a note needs company write access. Linking a contact to a company needs write access to both companies and contacts. Reading those links needs read access to both.

Tasks and offers require their own resource permission. You may link them to a known company UUID in your workspace without granting company read access. You cannot link records or assign users from another workspace.

Permission mask

Most integrations can use the settings page without handling the numeric mask. If you inspect /me, each resource occupies two bits, in order: companies (bits 0–1), contacts (2–3), offers (4–5), tasks (6–7). Values are 00 for none, 01 for read, and 11 for read and write. For example, 207 grants company, contact and task read/write, with no offer access. 255 grants all four resources read/write. Missing permissions grant no resource access.

Keep the key on your server

Use the API from your backend, scheduled job or automation platform. API keys do not belong in public JavaScript, a mobile application bundle, a URL, or a Git repository. This API does not enable browser CORS, and the documentation does not send authenticated API requests on your behalf.

Send Content-Type: application/json with POST and PATCH. The request body limit is 100 KB.

Rotate or remove a key

Create a replacement key, update your integration, verify /me, then delete the previous key in Aventra. Deleted and revoked keys stop authenticating on the next request; an already-running request can still finish. All keys are subject to their configured permissions.

Use a separate key for each integration so you can disable one without interrupting the others.