Skip to content

Authentication

Exchange your server key for a session token, then send the token on every other call:

Terminal window
export BEEKON_TOKEN=$(curl -sf -X POST https://api.in1.getbeekon.com/v1/token \
-H "Authorization: Bearer $BEEKON_SERVER_KEY" | jq -r .access_token)
curl -s https://api.in1.getbeekon.com/v1/project -H "Authorization: Bearer $BEEKON_TOKEN"

The server key (bkserv_<cell>_<secret>) is long-lived, stays in your backend’s secret store and goes to one endpoint only, POST /v1/token. The session token is short-lived. Because the key never travels on a data call, a leaked request log exposes at most a token that expires within the hour.

Exchanges a key for a session token. This is the only /v1 endpoint that takes no session.

Request — no body; the key rides the Authorization header:

Terminal window
curl -s -X POST https://api.in1.getbeekon.com/v1/token \
-H "Authorization: Bearer $BEEKON_SERVER_KEY"

Response 200:

{"access_token":"eyJhbGciOiJFUzI1NiIs…","expires_in":3600}
MemberTypeMeaning
access_tokenstringThe session token. Treat it as opaque: do not decode it or depend on its claims.
expires_inintegerSeconds until the token expires, counted from the response.

Errors

StatuserrorWhen
401missing bearer tokenNo Authorization header, an empty one, or a scheme other than Bearer.
401unknown project keyThe key is unknown, revoked, or belongs to another region’s host. One answer for all three.
400malformed project keyThe value is not shaped like a Beekon key.
500internal errorA failure on our side. Retry with backoff.
503project suspendedSDK keys only: the project is suspended, so no device session is minted. A server key still gets a token, so your backend can read why on GET /v1/project.

Like any endpoint, this one may also answer 429 or 503 while the platform protects itself; see Other limits.

The same endpoint serves SDK keys (bkproj_…), which is why the error text says “project key”. The key’s prefix decides which kind of session is minted; scopes come from the key.

Send the token as a bearer token on every other call:

Terminal window
curl -s https://api.in1.getbeekon.com/v1/project \
-H "Authorization: Bearer $BEEKON_TOKEN"

A session is bound to the project the key belongs to and to the key’s scopes. Nothing in a request can widen either.

StatuserrorWhen
401missing bearer tokenNo token, an empty one, or not Bearer.
401invalid session tokenThe token is expired, malformed, or was not issued by this region.
  • Read expires_in; do not hard-code the lifetime. It is one hour today and may change.
  • Re-mint before expiry (a minute of margin is plenty), and also on any 401 from a data call: mint once, then retry the request once. If the retry is also 401, stop and alert.
  • A new key works at once, and a revoked one stops at once. If a mint answers 401 unknown project key, retry it with backoff for up to 60 seconds before you alert. If it still fails, the key is unknown or revoked.
  • Tokens are cheap to mint, but cache them: one token per key per process is enough. Concurrent workers should share one refresh rather than each minting their own.
  • A 403 is never fixed by re-minting. It means the key lacks a scope, or the token was minted from the wrong kind of key.

Rotating a server key issues a replacement with the same scopes and name and revokes the old one at once. A revoked key can no longer mint tokens (401 unknown project key), and tokens already minted from it stop working at most 2 seconds after the revocation reaches your project’s region, which is normally at once: each call then answers 401 invalid session token. So a rotation is an immediate cutover: the old key stops as soon as you rotate. For zero downtime, issue a second key with the same scopes instead, move your backend to it, then revoke the old key. Change a key’s scopes the same way.