Exchange your server key for a session token, then send the token on every other call:
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.
POST /v1/token
Section titled “POST /v1/token”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:
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}| Member | Type | Meaning |
|---|---|---|
access_token | string | The session token. Treat it as opaque: do not decode it or depend on its claims. |
expires_in | integer | Seconds until the token expires, counted from the response. |
Errors
| Status | error | When |
|---|---|---|
| 401 | missing bearer token | No Authorization header, an empty one, or a scheme other than Bearer. |
| 401 | unknown project key | The key is unknown, revoked, or belongs to another region’s host. One answer for all three. |
| 400 | malformed project key | The value is not shaped like a Beekon key. |
| 500 | internal error | A failure on our side. Retry with backoff. |
| 503 | project suspended | SDK 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.
Using the token
Section titled “Using the token”Send the token as a bearer token on every other call:
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.
| Status | error | When |
|---|---|---|
| 401 | missing bearer token | No token, an empty one, or not Bearer. |
| 401 | invalid session token | The token is expired, malformed, or was not issued by this region. |
Expiry and re-minting
Section titled “Expiry and re-minting”- 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
401from a data call: mint once, then retry the request once. If the retry is also401, 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
403is never fixed by re-minting. It means the key lacks a scope, or the token was minted from the wrong kind of key.
Rotating and revoking keys
Section titled “Rotating and revoking keys”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.