# Keys and access

A key belongs to one admin and one community. It lets you do, through the API, what that admin could do in the app
for that community, and nothing more.

## Sending the key

Send it on every request, in the `Authorization` header, exactly like this:

```sh
curl "$API/organization" -H "Authorization: Bearer $KEY"
```

`Bearer`, one space, then the key (it starts with `zsc_`). The key is read from that header only: a key in the
address (`?access_token=…`) or in any other header is ignored, and the request answers `401`.

These instructions (the pages under `/docs/portability`, and its `llms.txt`) need no key.

## How long a key works

The admin chooses when they make it: **1 day, 1 week, 2 weeks or 4 weeks**. Four weeks is the longest, and a key
cannot be extended. If the work takes longer, the admin makes a new key and gives you its message.

A key stops working at once when:

- it expires;
- the admin revokes it;
- the admin who made it is no longer an owner or admin of the community.

## When the key does not work: 401

Every one of those causes, and a missing or mistyped header, answers the same:

```
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="Zen Social", error="invalid_token"

{"error":"invalid_token"}
```

The answer never says which cause it was. Check that you send the header exactly as above. If you do, stop and tell
the admin that the key no longer works: it may have expired or been revoked. They can make a new one in their
community's **Manage** page, tab **Import & AI access**, **New key**. Do not keep retrying.

## What the key may do: 403 and 404

The key acts as the admin who made it, with that admin's rights in the app:

- **`403 {"error":"forbidden"}`**: the key works, but the admin could not do this in the app. The common case: an
  admin of the community who is not in one of its circles can see that circle in `GET /circles` and `GET /circles/:id`,
  but cannot change it, delete it or read its member list. Ask the admin to join that circle in the app (and to be made
  its owner or admin there, if you are to change it). Do not look for a way around it.
- **`404 {"error":"not_found"}`**: it does not exist, or it belongs to another community. A key never reaches outside
  its own community, and the answer for something there is always `404`.

## How fast you may go: 429

At most **300 requests a minute per key**, and 600 a minute from one network address. Above that the answer is:

```
HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{"error":"Too many requests. Please try again later."}
```

Wait the number of seconds in `Retry-After`, then carry on where you stopped. Send one request at a time rather than
many at once.

## Keeping the key safe

- Anyone who has the key can change the community until it expires. Never put it in content you import, in files or
  messages you write for others, or in anything you show besides your own requests.
- If the key may have leaked, tell the admin to revoke it at once.
- When the work is done, tell the admin to revoke it: **Manage**, tab **Import & AI access**, **Revoke**. An assistant
  using it stops working at once.