# Authentication

> Exchange a server key for a short-lived session token at POST /v1/token, send it as a bearer token, and re-mint on expiry or 401.

Source: https://docs.getbeekon.com/api/authentication/

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

```sh
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`

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:

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

**Response** `200`:

```json
{"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`](https://docs.getbeekon.com/api/project/). |

Like any endpoint, this one may also answer `429` or `503` while the platform protects itself; see [Other limits](https://docs.getbeekon.com/api/rate-limits/#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

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

```sh
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

* 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](https://docs.getbeekon.com/api/scopes/), or the token was minted from the wrong kind of key.

Keep server keys out of apps

A server key reads your whole project’s location history. Keep it on your servers. Mobile apps use the SDK key (`bkproj_…`), which cannot read any server endpoint.

## 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.
