> ## Documentation Index
> Fetch the complete documentation index at: https://docs.a-char.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> API keys, scopes, and what a key is allowed to do.

Every request needs a key in the `Authorization` header:

```
Authorization: Bearer ak_...
```

Requests without one, or with a revoked or expired key, return `401`.

## Getting a key

Create a key from your account settings. It is shown **once, at creation** — only a hash is
stored, so it cannot be recovered or re-sent. If you lose one, revoke it and create another.

<Warning>
  Keep keys server-side. Never ship one in a browser, a mobile app, or a public repository.
</Warning>

## Keys belong to a person

A key is issued to **you**, not to your organization, and it acts within one organization.
Every response is limited to that organization — there is no parameter for choosing another,
and no way for a key to reach another tenant's data.

Because the key is yours, the API knows who is asking. That is what makes requests like
"my time off" meaningful rather than ambiguous.

## Scopes

A key carries scopes that say what it may do. Grant only what the integration needs.

| Scope                | Allows                                            |
| -------------------- | ------------------------------------------------- |
| `departments:read`   | `GET /departments`, `GET /departments/{id}`       |
| `departments:write`  | `POST /departments`, `POST /departments/{id}`     |
| `departments:delete` | `DELETE /departments/{id}`, `DELETE /departments` |

Deleting is deliberately separate from writing. An assistant that tidies up your data does not
need the ability to remove it, and a key can be created that reflects that.

A request for something the key lacks returns `403`, and the operation does not run.

## Your role is the ceiling

Scopes narrow what you can do — they never widen it.

| Your role | Most a key of yours can do |
| --------- | -------------------------- |
| Admin     | read, write, delete        |
| Member    | read                       |

So a member's key requesting `departments:write` is created, but that scope has no effect: the
request returns `403`. Your role is read at the time of each request, so if it changes, your
existing keys follow immediately.

## Expiry and revocation

A key can be given an expiry, and can be revoked at any time. Both take effect on the next
request, which then returns `401`.