Sessions

A session represents a signed-in device. From the backend you can mint one headlessly (for agents, testing, or impersonation), list a user's sessions, and revoke them.

{
  "object": "session",
  "id": "sess_…",
  "user_id": "user_2a…",
  "status": "active",
  "last_active_organization_id": "org_9f…",
  "impersonated_by": null,
  "last_active_at": 1757600000000,
  "expire_at": 1757603600000,
  "abandon_at": 1757800000000,
  "created_at": 1757600000000
}

Endpoints

Related, on the Users API: GET /v1/users/:id/sessions and POST /v1/users/:id/sessions/revoke (revoke all).

Minting a session

POST /v1/sessions returns the credentials in-body — the sk_ caller already holds full power, so this saves the browser redeem/exchange hops. Store the refresh_token to keep the session alive.

curl https://api.atlas.dev/v1/sessions \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"user_2a"}'

{
  "object": "session",
  "id": "sess_…",
  "user_id": "user_2a…",
  "jwt": "eyJhbGciOiJSUzI1Ni␣…",
  "refresh_token": "…",
  "expires_in": 60
}

Impersonation

Pass an actor.sub to mint an impersonation session; the minted session carries the RFC 8693 act claim naming the impersonator, and the action is always audited.

const s = await atlas.sessions.create({ user_id: 'user_2a', actor: { sub: 'user_admin' } });

For a redeemable impersonation credential instead of a live session, use POST /v1/actor_tokens (scope impersonation:write) or the one-time POST /v1/sign_in_tokens (scope sign_in_tokens:write).

Listing & revoking

const page = await atlas.sessions.list({ user_id: 'user_2a' });
await atlas.sessions.revoke('sess_123');

// Revoke everything a user holds (also bumps sessions_version)
await atlas.users.revokeSessions('user_2a');