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:

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.