Authentication
One key, scoped to one directory and to the capabilities you ticked, sent as a bearer token. There is no sign-in step and no token to exchange first.
Sending the key
Every request carries the key in an Authorization header. The key you copied from the console is the bearer token.
Authorization: Bearer YOUR_KEYThe header is the only place we read it. A key sent as a query parameter is refused, because a URL ends up in access logs, Referer headers and browser history.
What a key may do
A key carries only the capabilities you ticked when you made it. They are not a hierarchy — writing does not imply reading, and neither implies triggering a check.
- listings:read — Read the directory's listings, one page at a time, and read any single listing.
- listings:write — Create and edit listings, and publish, unpublish or archive them.
- directories:read — Read the directory's own name, description and linkback policy.
- directories:write — Change the directory's details and its linkback policy.
- taxonomy:read — Read the directory's categories, tags and collections.
- actions:trigger — Ask for a linkback check or a Domain Rating refresh. Both cost us an outbound request, so both are rate limited.
What a key cannot do
A key narrows access; it never grants it. It can only ever do less than the person who made it, never more, and it reaches exactly one directory.
It works only while you are still a member of the account that owns the directory. Leaving the account stops the key on its next request, with nobody having to revoke anything. So does revoking it in the console.
The API answers on our own domain only, never on a directory's custom domain.
How a refusal reads
Three refusals are about the key rather than the request. We answer 404 for every way of missing — the wrong directory, a revoked membership, a key that names no directory — because a refusal must not reveal that a record exists.
- 401 invalid_token — The key is missing, unreadable or revoked.
- 403 insufficient_scope — The key is valid but does not carry the capability this endpoint needs.
- 404 not_found — The directory is not the one this key was issued for, the record is not in it, or you are no longer a member of the account that owns it. We answer the same way in every case, on purpose.