Sessions
How long a Botanary session lasts, how it ends, and what the session-lock state actually means.
A Botanary session is deliberately short-lived and easy to end. This page covers the session/session-lock concept - not delegation session keys, which is a completely different mechanism covered in ERC-7579 modules.
Lifetime
A session token is issued with a one-day expiry, set at creation time and enforced server-side on
every single request by the same SessionGuard that checks the token's existence in the first place
- an expired token fails auth exactly the same way a missing one does. When a session expires, the frontend re-authenticates through the same Privy exchange described in Authentication.
TODO: no session-refresh endpoint was found in the current contract - verify the refresh flow before documenting.
Ending a session
DELETE /auth/session ends the session and returns 204. Server-side, this is a straightforward
delete of the stored session record - there's no soft-expire step, no grace period. The endpoint
description makes the custody point explicit: "Invalidates the session token. Funds never left the
owner's account." Ending a session is purely about access to the API - it has no bearing on anything
that's been granted or deployed on-chain.
Ending a session is about availability, not custody. Everything you've granted stays exactly as bounded and revocable as it was before - a session ending doesn't touch it.
The locked field
SessionContext.locked is a boolean the session-lock UI (the topbar lock screen) reads and drives -
its own description calls it out directly as "session-lock state." It's returned as part of the
context from GET /auth/session, alongside the token itself.
There's no dedicated lock endpoint in the current contract - locked is a field you read on the
session context, not something you flip with its own POST. Treat session-lock as UI-level state
layered on top of the session, not a separate backend primitive, until that changes.
Chains carried on the session
The chains array on a session is computed once, at creation time, narrowed down to whatever chains
the account is actually allowed to use - and that same narrowed list gets reused as the fallback chain
set by downstream build paths (account deployment, for one) rather than being recomputed from
scratch each time.
What the frontend actually checks
The frontend's session hook exposes { ready, authenticated, sessionReady, authError, ownerAddress, logout }. sessionReady is the one worth understanding: it's true only once both halves of the
build-sign-relay chain are wired up - the embedded signer and the Botanary session token - which is
the frontend's own definition of "ready to build, sign, and relay." Nothing that requires a signature
should be attempted before it's true.