Skip to content

Auth & token refresh

Once sync is on, every upload can carry credentials your ingest endpoint checks. This page covers the two ways to attach them and how the SDK keeps a rotating token fresh.

On this topic: Turn on sync · Upload payload & ingest endpoint · Auth & token refresh (this page)

There are two ways to authenticate uploads:

  • Static header: a fixed API key in SyncConfig.headers. It never rotates, and it is stored in plaintext on the device.
  • Declarative refresh: an AuthConfig recipe. The SDK attaches a bearer token and refreshes it against your token endpoint: before it expires, and again after a 401 or 403. Refresh runs in the background and after a cold launch, with no callback into your app code.

Use the static header for low-stakes keys; use AuthConfig for anything that should rotate.

SyncConfig(
url = "https://api.example.com/locations",
auth = AuthConfig(
accessToken = "<initial access token>", // seed, optional
refreshToken = "<initial refresh token>", // seed
expiresAt = System.currentTimeMillis() / 1000 + 3600, // epoch seconds
refreshUrl = "https://auth.example.com/oauth/token",
refreshPayload = mapOf(
"grant_type" to "refresh_token",
"refresh_token" to "{refreshToken}", // substituted at refresh time
),
// strategy = AuthStrategy.Bearer, refreshBodyFormat = AuthBodyFormat.Form,
// skewMarginSeconds = 60 (all defaults)
),
)

The tokens you pass are a seed. The SDK adopts them once, then keeps and rotates the live tokens in encrypted storage (Keychain on iOS, Keystore on Android). Passing the same or a different seed again later changes nothing while a token is stored, unless you raise seedEpoch. Each rotation arrives on the authChanges stream (onAuthTokens in React Native); copy it into your own session store if you need it.

FieldDefaultMeaning
accessTokennoneSeed access token (optional).
refreshTokennoneSeed refresh token, or another long-lived credential.
expiresAtnoneSeed expiry: epoch seconds on Android (Long) and iOS (TimeInterval), a DateTime in Flutter, a Date in React Native. Without it there is no proactive refresh, only the refresh after a 401 or 403.
strategyBearerHow the token is attached: Bearer sends Authorization: Bearer <token>; Raw sends Authorization: <token>.
refreshUrlnoneToken endpoint. Without it the SDK uses the seed and never refreshes.
refreshPayload{}Request body fields. {accessToken} / {refreshToken} are substituted with the current tokens.
refreshHeadersAuthorization: Bearer {accessToken}Request headers, same templating.
refreshBodyFormatFormForm (application/x-www-form-urlencoded) or Json.
responseMappingnoneOverrides the keys Beekon reads from the response. Dot paths such as data.access_token work.
skewMarginSeconds60Refresh this many seconds before expiresAt.
seedEpochnoneA number you raise to replace the stored tokens with a new seed, for example after the user signs in again. When it is greater than the stored epoch, the SDK adopts the seed you pass. Without it, a seed is adopted only when no token is stored yet. An integer on every platform (Long on Android).

To refresh, the SDK sends a POST to refreshUrl with the templated payload (15 s timeout) and reads the new token from the response. Answer 2xx with JSON:

{ "access_token": "<new token>", "expires_in": 3600 }

Beekon reads the token from the first key present: responseMapping.accessToken, then access_token, accessToken, token. It reads the expiry from the first of responseMapping.expiresAt (an absolute time in epoch seconds), responseMapping.expiresIn (seconds from now), expires_at and expires_in; it never looks for camelCase expiry keys in the response unless you map them. A numeric string such as "3600" works.

Refresh returnsOutcome
2xx with a tokenAdopt the new token set, retry the upload.
2xx without a tokenDead credentials. Refreshing stops until you re-seed.
408, 429, 5xx, network error or timeoutTransient. Back off and retry.
3xx or any other 4xxDead credentials. Refreshing stops until you re-seed.

After 3 refresh failures in a row, the SDK backs off exponentially so it doesn’t flood your token endpoint. To recover from dead credentials, call configure() with a new accessToken and a higher seedEpoch.

  • Proactive: when expiresAt is set, the refresh runs at expiresAt − skewMarginSeconds, before a request fails.
  • Reactive: a 401 or 403 triggers one refresh, then the upload is retried once.
  • One refresh at a time: concurrent requests share one refresh, so a burst sends one request to your endpoint.
  • Stored encrypted: rotated tokens survive process death. The upload backlog is kept while auth is failing, so no location is lost.

Next: if uploads fail, the sync checklist lists the usual causes.