Authentication

Authorization: Bearer lsk_7mKq2xV9…

Send the key as a bearer token. Authorization: Bearer rather than an X-API-Key header, for two reasons worth knowing: that header is already taken on loso’s internal API by a credential that means something entirely different, and bearer is what every HTTP client library already knows how to send.

curl "https://api.locally-social.com/api/v1/categories" \
  -H "Authorization: Bearer $LOSO_API_KEY"

Formatstring

lsk_ followed by a URL-safe 256-bit secret — one token, no environment segment, the same shape on every tier. The prefix is there so a leaked key is recognisable on sight in a repository scan, a log line or a support ticket, without anybody having to look it up.

Shown once—

The secret appears exactly once, in the response that mints it. loso stores only a hash and cannot show it again. Lost means revoke and mint a new one.

Scopesstring[]

Every key is issued with events:read, which is the only scope that exists. A key stores the scopes it was minted with, so a scope added later does not retroactively widen keys already issued.

How manyinteger

One to five live at once, by tier. More than one so a key can be rotated without downtime; few enough that fresh keys cannot multiply an account's own rate limit.

Rate limits are counted per key, not per account. A noisy job given its own key therefore throttles itself rather than starving the rest of the integration — which is also the fastest way to find out which job is noisy.

An approved account starts on the trial tier. Its keys are real and its responses are real rows, confined to one ZIP code.

/categories and /cities are not fenced. They report the full corpus on every tier, so the vocabularies tell you what live access covers before you have it.

Going live is a second decision, made after there is something built against the trial. Ask from the portal, or email [email protected].

Mint the replacement first, deploy it, then revoke the old one. Revocation takes effect on the next request — there is no grace window, and a key revoked while still deployed fails every call immediately.

Both keys authenticate during the overlap, each against its own rate limit. Accounts limited to one live key have to revoke before minting, so plan the cutover.

Every refusal below carries a detail string naming the cause. They are distinguishable on purpose: all four need a different fix, and a generic 401 sends a developer to support instead of to their dashboard.

401 missingno header

Send your key as `Authorization: Bearer <key>`.

401 unknownbad key

Invalid API key — one uniform answer, so this cannot be used to learn which guesses were ever real keys.

401 revokeddead key

Names revocation and expiry separately, because the holder is the only person who can fix either and the fix is the same: mint a new one.

403 accountnot approved

The account is still under review, was not approved, or is suspended. The message says which.

403 fencetrial key

A trial key named a location outside its ZIP. The message names the ZIP and what to remove.

{ "detail": "Send your key as `Authorization: Bearer <key>`." }