# API and keys (https://docs.akollo.com/en/connections/api)



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 [#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 [#create-an-api-key]

<Steps>
  <Step>
    ### Open API keys [#open-api-keys]

    Go to **Integrations → API keys** and open the form to create a key.
  </Step>

  <Step>
    ### Name the key and pick the service account [#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.
  </Step>

  <Step>
    ### Choose the scopes [#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.
  </Step>

  <Step>
    ### Set the expiry and addresses [#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.
  </Step>

  <Step>
    ### Create and store the key [#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_`.
  </Step>
</Steps>

<Callout type="info" title="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.
</Callout>

### Roll or revoke a key [#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.

<Steps>
  <Step>
    ### Find the key [#find-the-key]

    In **Integrations → API keys**, find the key in the list.
  </Step>

  <Step>
    ### Revoke it with a reason [#revoke-it-with-a-reason]

    Choose **Revoke** and enter a **Reason**. The key's state changes to **Revoked**.
  </Step>
</Steps>

## The public API [#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 [#requests-retries-and-limits]

A write sends an `Idempotency-Key`, so a program can safely repeat a request after a timeout.

<Mermaid
  title="How a repeated write is handled"
  chart="`sequenceDiagram
participant P as Program
participant A as Akollo
P->>A: Write with Idempotency-Key and body
A-->>P: First response
P->>A: Same key and same body within 24 hours
A-->>P: The first response again
P->>A: Same key with a different body
A-->>P: Refused`"
/>

| 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 [#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 [#faq]

<Accordions type="single">
  <Accordion title="I lost an API key. Can I see it again?">
    No. A key is shown once. Roll the key to get a new one; the previous key keeps working for a short grace period.
  </Accordion>

  <Accordion title="Why is my new key waiting for approval?">
    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.
  </Accordion>

  <Accordion title="Can a key do more than its service account?">
    No. What a key can do is always limited to what its service account's role allows.
  </Accordion>

  <Accordion title="Is it safe to repeat a write after a timeout?">
    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.
  </Accordion>

  <Accordion title="What happens when I call too often?">
    Each caller has a per-minute limit. When it is reached, the response says when to retry.
  </Accordion>
</Accordions>

## Related pages [#related-pages]

* [BI datasets](/en/connections/bi-datasets)
* [Webhooks](/en/connections/webhooks)
* [Connected systems](/en/connections)