Session Management Endpoints

Base URL: https://auth.calimatic.com/api/v1/auth/headless

Session management endpoints use App Client authentication. These endpoints allow your application to list, revoke individual, or revoke all active sessions for a user.

Authentication

All endpoints in this group use App Client authentication:

Header	Value	Description
`x-client-id`	`cca_...`	Your app client ID
`x-client-secret`	`ccas_...`	Your app client secret

Endpoints Overview

Method	Endpoint	Description
`GET`	`/sessions?userId=...`	List all active sessions for a user
`DELETE`	`/sessions/{id}`	Revoke a specific session by session ID
`DELETE`	`/sessions`	Revoke all sessions for a user

GET /api/v1/auth/headless/sessions

List all active Keycloak sessions for a given user. Returns session details including IP address, user agent, and last activity time where available.

Authentication: App Client (x-client-id + x-client-secret)

Query Parameters

Parameter	Type	Required	Description
`userId`	string	Yes	ID of the user whose sessions to list

Response (200 OK)

{
  "sessions": [
    {
      "id": "session-uuid-1",
      "application": "calimatic-app",
      "ipAddress": "192.168.1.1",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
      "createdAt": "2025-01-15T09:00:00.000Z",
      "lastActiveAt": "2025-01-15T10:30:00.000Z"
    },
    {
      "id": "session-uuid-2",
      "application": "calimatic-mobile",
      "ipAddress": "10.0.0.1",
      "userAgent": "CalimaticApp/1.0 (iOS 17.0)",
      "createdAt": "2025-01-14T15:00:00.000Z",
      "lastActiveAt": "2025-01-15T08:00:00.000Z"
    }
  ]
}

Response Fields

Field	Type	Description
`sessions`	array	List of active session objects
`sessions[].id`	string	Unique session identifier
`sessions[].application`	string	Application that created the session
`sessions[].ipAddress`	string (optional)	IP address of the client
`sessions[].userAgent`	string (optional)	User agent string of the client
`sessions[].createdAt`	string	ISO 8601 timestamp when session was created
`sessions[].lastActiveAt`	string (optional)	ISO 8601 timestamp of last activity

Error Codes

Code	HTTP Status	Description
`USER_NOT_FOUND`	404	User does not exist
`INVALID_CLIENT`	401	App client credentials are missing or invalid
`RATE_LIMITED`	429	Request rate limit exceeded

SDK Method

const { sessions } = await client.sessions.list({ userId: 'user-uuid' });
console.log(`User has ${sessions.length} active sessions`);

curl Example

curl -X GET "https://auth.calimatic.com/api/v1/auth/headless/sessions?userId=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "x-client-id: cca_aBcDeFgHiJkL" \
  -H "x-client-secret: ccas_xYzAbCdEfGhI"

DELETE /api/v1/auth/headless/sessions/{id}

Revoke a specific session by session ID. Immediately terminates the specified session. The user will need to log in again to create a new session.

Authentication: App Client (x-client-id + x-client-secret)

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	ID of the session to revoke (from sessions list)

Request Body

None.

Response (200 OK)

Returns an empty body on success.

{}

Error Codes

Code	HTTP Status	Description
`USER_NOT_FOUND`	404	Session does not exist
`INVALID_CLIENT`	401	App client credentials are missing or invalid
`RATE_LIMITED`	429	Request rate limit exceeded

SDK Method

await client.sessions.revoke({ sessionId: 'session-id' });

curl Example

curl -X DELETE "https://auth.calimatic.com/api/v1/auth/headless/sessions/session-uuid-1" \
  -H "x-client-id: cca_aBcDeFgHiJkL" \
  -H "x-client-secret: ccas_xYzAbCdEfGhI"

DELETE /api/v1/auth/headless/sessions

Revoke all active sessions for a user. Terminates all current sessions across all devices. The user will need to log in again from all devices.

Authentication: App Client (x-client-id + x-client-secret)

Request Body

Field	Type	Required	Description
`userId`	string	Yes	ID of the user whose sessions to revoke
`revokedBy`	string	No	Optional ID of the admin user performing the action (for audit logging)

Response (200 OK)

{
  "revokedCount": 3
}

Error Codes

Code	HTTP Status	Description
`USER_NOT_FOUND`	404	User does not exist
`INVALID_CLIENT`	401	App client credentials are missing or invalid
`RATE_LIMITED`	429	Request rate limit exceeded

SDK Method

const { revokedCount } = await client.sessions.revokeAll({ userId: 'user-uuid' });
console.log(`Revoked ${revokedCount} sessions`);

curl Example

curl -X DELETE https://auth.calimatic.com/api/v1/auth/headless/sessions \
  -H "Content-Type: application/json" \
  -H "x-client-id: cca_aBcDeFgHiJkL" \
  -H "x-client-secret: ccas_xYzAbCdEfGhI" \
  -d '{
    "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "revokedBy": "admin-user-uuid"
  }'