Skip to main content

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

Call createSession right before you hand control to the agent. The token is shown exactly once.
The returned 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

Call consumeAction once per agent action to decrement the budget counter.
When 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.
Revocation also revokes the underlying agent. It is idempotent, calling it on an already-revoked session returns success. An unknown session ID returns a SESSION_NOT_FOUND error.

Listing active sessions

Useful for dashboards or for building kill-switch UI.
The returned objects have 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

Run cleanupExpired() 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

When auditGrouping: 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

A session starts as 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

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.
Last modified on October 18, 2026