What ephemeral sessions are
An ephemeral session is a temporary agent identity that expires on its own. You create one, hand the token to an AI agent, and the token stops working when the TTL runs out or the agent exhausts its action budget, whichever comes first. The pattern is designed for computer-use agents (Claude computer use, GPT browsing, operator loops) that need just enough access to complete one task without holding persistent credentials across invocations. Key differences from a regular agent:Setup
No extra configuration is needed, ephemeral sessions are part of the@glinr/theauth core package and share the same database as the rest of theAuth.
Creating a session for a computer-use agent
CallcreateSession right before you hand control to the agent. The token is shown exactly once.
token is kveph_ followed by 64 hex characters, to distinguish it from long-lived agent tokens (ta_, or legacy kv_). Only its SHA-256 hash is stored. Creating a session also creates a temporary agent (type autonomous) that holds the permissions, so result.data includes agentId as well. ttlSeconds above maxTtlSeconds returns a TTL_EXCEEDS_MAX error, and permissions must contain at least one entry.
Validating a session
Each time the agent makes a request, validate the token before granting access.expiresIn is in seconds. remainingActions is null when no action cap was set.
Tracking actions
CallconsumeAction once per agent action to decrement the budget counter.
actionsRemaining hits zero, the session transitions to exhausted, and the underlying agent is revoked if autoRevokeOnExpiry is on (the default). Further calls return SESSION_EXHAUSTED. After the session leaves active, consumeAction returns SESSION_EXPIRED, SESSION_REVOKED or SESSION_EXHAUSTED accordingly.
Action limits
maxActions is a hard cap on how many times consumeAction can succeed. It is independent of the TTL, a session can expire by time with actions remaining, or exhaust its action budget before the TTL lapses.
Set a tight budget for tasks with a well-known scope and leave it as null for tasks where the step count is unpredictable.
Revoking early
If the agent completes the task before the TTL expires, revoke the session manually.SESSION_NOT_FOUND error.
Listing active sessions
Useful for dashboards or for building kill-switch UI.token set to "", the token is never readable after the initial createSession response.
Cleanup strategies
Two approaches to cleaning up expired sessions:Scheduled background job
RuncleanupExpired() on a cron schedule, every minute for busy systems, every 5 minutes for lighter loads.
On-demand at validate time
validateSession already detects and transitions expired sessions. For low-traffic systems, this is enough, no background job needed.
Audit grouping
WhenauditGrouping: true (the default), the session gets its own auditGroupId. With auditGrouping: false, auditGroupId is set to the session ID instead. theAuth returns the ID from validateSession but does not stamp it onto audit entries for you, so attach it to the entries you record. That makes it straightforward to reconstruct the full activity trace for a single task.
Session status lifecycle
active. Once it leaves active, it cannot be reactivated. Create a new session for a new task. Expiry is recorded lazily, when the session is next validated, listed, or swept by cleanupExpired().
Error codes
Related
Agent identity
Long-lived agent identities that ephemeral sessions are built on top of.
Delegation
Hand a subset of permissions to a sub-agent with depth limits.
Audit trail
Audit trail for agent activity.
Sessions
Cookie and JWT sessions, plus how they differ from ephemeral agent sessions.