API and keys
Other systems reach Akollo through the public API with an API key. Administrators create the keys. Each key carries only the scopes it needs and can be revoked at any time.
API keys
Integrations → API keys lists each key with:
| Column | What it shows |
|---|---|
| Name | The name you gave the key |
| Key | The first characters of the key |
| Service account | The service account the key acts as |
| Scopes | What the key may read |
| Expires | The expiry date |
| Last used | When the key was last used |
| State | Waiting for approval, Active, Rolling, Revoked or Expired |
A key waiting for approval shows who must approve it.
Create an API key
Open API keys
Go to Integrations → API keys and open the form to create a key.
Name the key and pick the service account
Give the key a name that says which system uses it. Pick the Service account the key acts as. What a key can do is always limited to what its service account's role allows.
Choose the scopes
Set each scope the key needs to Read and leave the rest at None. The Work items and Filters scopes are offered as read only.
Set the expiry and addresses
Set an expiry date; a key expires within a year. Optionally list the Allowed IP ranges the key may be used from, one per line.
Create and store the key
Choose Create key. The key is shown once. Copy it, store it safely and confirm that you stored it. It starts with akl_live_ or akl_test_.
Note
A key that needs approval, for example one that can change records, waits until a different administrator approves it. The person who created a key cannot approve it.
Roll or revoke a key
- Roll replaces a key. The previous key keeps working for a short grace period, so you can update the system that uses it. The key shows the state Rolling meanwhile.
- Revoke withdraws a key at any time.
Find the key
In Integrations → API keys, find the key in the list.
Revoke it with a reason
Choose Revoke and enter a Reason. The key's state changes to Revoked.
The public API
Programs call /api/public/v1 and send the date of the API version they were built against in the Akollo-Version header.
- With a read scope, a key can list and fetch projects, tasks, tracked employees and daily time summaries.
- The Work items and Filters scopes let a key also read work items, search them, read saved filters and views, list a work item's attachments and download them.
- Lists return a page of records and a cursor for the next page. Each list accepts a page size, a cursor and a time to read changes since.
- A missing record and a record from another organisation look the same.
- A daily summary is returned only if the caller may see that person's day. It gives the date, worked and credited time, and whether the figure is still current. It does not include activity, captures or task splits.
- Errors are problem documents. An error never describes a record that belongs to another organisation.
- Files and CSV exports are returned as they are, with their own content type.
Requests, retries and limits
A write sends an Idempotency-Key, so a program can safely repeat a request after a timeout.
| Situation | Result |
|---|---|
Same Idempotency-Key and same body within 24 hours | The first response is returned; the write does not run again. |
Same Idempotency-Key with a different body | Refused. |
| First response larger than 64 KiB | Not stored. Repeating that key is refused and does not run again. |
| Per-minute limit reached | Each caller has a per-minute limit. The response says when to retry. |
Developer reference
The OpenAPI description of the enabled operations is at /api/public/v1/openapi.json (and .yaml).
Integrations → Developer shows every route for the selected version, the scope it requires and an example curl request. The key in that example is always a placeholder; the page never sends a request with a real key. Deprecated and sunsetting routes carry a badge. Routes of a disabled module are not listed.
FAQ
No. A key is shown once. Roll the key to get a new one; the previous key keeps working for a short grace period.
A key that needs approval, for example one that can change records, waits until a different administrator approves it. The person who created it cannot approve it.
No. What a key can do is always limited to what its service account's role allows.
Yes, if you send the same Idempotency-Key and the same body within 24 hours. You get the first response and the write does not run twice.
Each caller has a per-minute limit. When it is reached, the response says when to retry.