Sessions API

Sessions represent an authenticated period for a user. A session contains an access token (short-lived) and a refresh token (long-lived).

Session Object

{
  "id": "ses_01HABCDEF999888",
  "user_id": "usr_01HABCDEF123456",
  "tenant_id": "tnt_01HABCDEF654321",
  "status": "active",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
  "ip_address": "203.0.113.42",
  "country": "US",
  "device_type": "desktop",
  "created_at": "2024-01-15T10:30:00Z",
  "last_active_at": "2024-01-20T08:15:00Z",
  "expires_at": "2024-02-14T10:30:00Z"
}

GET /v1/sessions

List all active sessions for the tenant.

Headers: Authorization: Bearer sk_live_... + X-Tenant-ID

Query parameters:

Parameter	Type	Description
`user_id`	string	Filter by user ID
`status`	string	`active`, `expired`, `revoked`
`limit`	integer	Default `20`, max `100`
`cursor`	string	Pagination cursor

curl "https://api.hellojohn.dev/v1/sessions?user_id=usr_01HABCDEF123456" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321"

GET /v1/sessions/:id

Fetch a single session by ID.

curl https://api.hellojohn.dev/v1/sessions/ses_01HABCDEF999888 \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321"

Response: 200 OK — Returns Session object.

DELETE /v1/sessions/:id

Revoke a specific session immediately. The associated access token and refresh token become invalid.

curl -X DELETE https://api.hellojohn.dev/v1/sessions/ses_01HABCDEF999888 \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321"

Response: 204 No Content

POST /v1/sessions/verify

Verify an access token and return the session payload. Use this on your backend to authenticate incoming requests.

Body:

Field	Type	Required	Description
`token`	string	✅	JWT access token to verify

curl -X POST https://api.hellojohn.dev/v1/sessions/verify \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321" \
  -H "Content-Type: application/json" \
  -d '{"token": "eyJhbGciOiJFZERTQSJ9..."}'

Response:

{
  "valid": true,
  "session_id": "ses_01HABCDEF999888",
  "user_id": "usr_01HABCDEF123456",
  "tenant_id": "tnt_01HABCDEF654321",
  "role": "member",
  "org_id": "org_01HABCDEF777666",
  "mfa_verified": true,
  "expires_at": "2024-01-15T11:30:00Z"
}

Note: For high-throughput backends, prefer local JWT verification using the JWKS endpoint (/.well-known/jwks.json) over this API call. See Token Verification.

DELETE /v1/sessions

Revoke all sessions for the tenant, or all sessions for a specific user.

Query parameters:

Parameter	Type	Required	Description
`user_id`	string	—	Limit revocation to this user

# Revoke all sessions for one user
curl -X DELETE "https://api.hellojohn.dev/v1/sessions?user_id=usr_01HABCDEF123456" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321"

Response:

{ "revoked": 7 }

Sessions API

On this page