Skip to main content

Auth Sessions API Reference

Overview

The Auth Sessions API provides comprehensive management tools for user authentication sessions on your Publica.la platform. It enables you to monitor active sessions, manage user access, and maintain security by terminating sessions when needed.

This API is particularly useful for administrators who need to monitor user activity, implement security policies, or manage user access across multiple devices and browsers.

info

Make sure you generated the api_token on your store. More info in the API Authentication guide

Endpoint Reference

EndpointMethodDescription
/integration-api/v1/auth-sessionsGETList authentication sessions with optional filtering
/integration-api/v1/auth-sessions/(id)DELETEDelete a specific authentication session
/integration-api/v1/auth-sessions/users/(user_id)DELETEDelete all authentication sessions for a user

List Auth Sessions

Retrieve a paginated list of authentication sessions with optional filtering by user.

Endpoint: GET /integration-api/v1/auth-sessions

Query Parameters

ParameterTypeDescriptionExample
user_idintegerFilter sessions by specific user ID?user_id=123
external_idstringFilter sessions by specific user external ID?external_id=user-123
per_pageintegerNumber of results per page (1-200, default: 100)?per_page=50
cursorstringPagination cursor for next page?cursor=eyJsYXN0X2FjdGl2aXR5Ijo...

Response Fields

FieldDescriptionType
CODEResponse status codestring
dataArray of auth session objectsarray
pagination.per_pageNumber of items per pageinteger
pagination.next_cursorCursor for next page (if available)string/null
pagination.has_moreWhether more pages are availableboolean

Auth Session Object Fields

FieldDescriptionType
idUnique session identifierstring
user_idID of the user who owns this sessioninteger
user_emailEmail of the user who owns this sessionstring
user_external_idExternal ID of the user who owns this sessionstring/null
ip_addressIP address from which session was createdstring
session_dataSession information (web browser or mobile app details)object
last_activityLast activity timestamp in ISO formatstring
last_activity_diffHuman-readable time since last activitystring
session_expires_atSession expiration timestamp in ISO formatstring

Example Request

GET /integration-api/v1/auth-sessions?user_id=123&per_page=25

Or filter by external ID:

GET /integration-api/v1/auth-sessions?external_id=user-123&per_page=25

Example Response

{
"CODE": "success",
"data": [
{
"id": "abc123def456ghi789",
"user_id": 123,
"user_email": "[email protected]",
"user_external_id": "user-id-in-your-platform",
"ip_address": "192.168.1.100",
"session_data": {
"browser": "Chrome",
"device": "Desktop",
"os": "macOS",
"type": "web",
"raw": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36"
},
"last_activity": "2023-12-29T10:00:00",
"last_activity_diff": "10 minutes ago",
"session_expires_at": "2023-12-29T12:00:00"
},
{
"id": "def789ghi123abc456",
"user_id": 123,
"user_email": "[email protected]",
"user_external_id": "user-id-in-your-platform",
"ip_address": "192.168.1.101",
"session_data": {
"app_name": "Publica Reader",
"app_version": "2.1.0",
"os": "iOS",
"os_version": "17.2",
"type": "mobile",
"raw": "PublicaReader/2.1.0 iOS/17.2"
},
"last_activity": "2023-12-29T09:45:00",
"last_activity_diff": "25 minutes ago",
"session_expires_at": "2024-12-29T09:45:00"
}
],
"pagination": {
"per_page": 25,
"next_cursor": "eyJsYXN0X2FjdGl2aXR5IjoxNzAzODc1MjAwLCJpZCI6ImFiYzEyM2RlZjQ1NmdoaTc4OSJ9",
"has_more": true
}
}

Response Codes

CodeDescription
200Success
422Validation error (invalid parameters)
401Unauthorized (invalid API token)

Session Data Structure

The API returns session information through the session_data field, which provides detailed information about each authentication session.

Web Sessions

Web sessions are created when users log in through a browser and contain browser-specific information:

{
"session_data": {
"browser": "Chrome", // Browser name (Chrome, Firefox, Safari, etc.)
"device": "Desktop", // Device type (Desktop, Mobile, Tablet)
"os": "macOS", // Operating system
"type": "web", // Always "web" for browser sessions
"raw": "Mozilla/5.0..." // Original user agent string
}
}

Mobile Sessions

Mobile sessions are created when users authenticate through mobile applications (Publica.la Reader or any custom tenant apps) and contain app-specific information:

{
"session_data": {
"app_name": "Publica Reader", // Application name
"app_version": "2.1.0", // App version
"os": "iOS", // Mobile operating system
"os_version": "17.2", // OS version
"type": "mobile", // Always "mobile" for app sessions
"raw": "PublicaReader/2.1.0..." // Original user agent string
}
}

Session Type Detection

You can easily distinguish between web and mobile sessions by checking the session_data.type field:

  • "type": "web" indicates a browser-based session
  • "type": "mobile" indicates a mobile app session

This allows you to implement different handling logic for each session type in your integration.

Delete Specific Session

Delete a specific authentication session by its ID.

Endpoint: DELETE /integration-api/v1/auth-sessions/(id)

Path Parameters

ParameterTypeDescriptionRequired
idstringThe session ID to deleteYes

Example Request

DELETE /integration-api/v1/auth-sessions/abc123def456ghi789

Example Response

{
"CODE": "success",
"message": "Session deleted successfully"
}

Response Codes

CodeDescription
200Session deleted successfully
404Session not found
401Unauthorized (invalid API token)

Delete All User Sessions

Delete all authentication sessions for a specific user.

Endpoint: DELETE /integration-api/v1/auth-sessions/users/(user_id)

Path Parameters

ParameterTypeDescriptionRequired
user_idintegerThe user ID whose sessions should be deletedYes

Example Request

DELETE /integration-api/v1/auth-sessions/users/123

Example Response

{
"CODE": "success",
"message": "Deleted 3 sessions successfully",
"data": {
"deleted_count": 3
}
}

Response Codes

CodeDescription
200Sessions deleted successfully
404User not found
401Unauthorized (invalid API token)

Use Cases

Security Management

Monitor and manage user sessions to maintain platform security:

  • Identify suspicious activity: Review sessions from unusual IP addresses or locations
  • Enforce device limits: Monitor concurrent sessions per user
  • Immediate access revocation: Quickly terminate compromised sessions

Administrative Tasks

  • User support: Help users manage their active sessions
  • Account cleanup: Remove old or inactive sessions
  • Access control: Ensure users only have authorized active sessions

Integration Examples

// Analyze user session patterns
const userId = 123;

const response = await fetch(`/integration-api/v1/auth-sessions?user_id=${userId}`, {
headers: {
'X-User-Token': 'your-api-token'
}
});

const result = await response.json();
const sessions = result.data;

// Categorize sessions by type
const webSessions = sessions.filter(s => s.session_data.type === 'web');
const mobileSessions = sessions.filter(s => s.session_data.type === 'mobile');

console.log(`User has ${webSessions.length} web sessions and ${mobileSessions.length} mobile sessions`);

// Get details about mobile apps being used
const mobileApps = mobileSessions.map(s => ({
app: s.session_data.app_name,
version: s.session_data.app_version,
platform: `${s.session_data.os} ${s.session_data.os_version}`,
lastActive: s.last_activity_diff
}));

console.log('Mobile app usage:', mobileApps);

// Get browser information
const browsers = webSessions.map(s => ({
browser: s.session_data.browser,
device: s.session_data.device,
os: s.session_data.os,
lastActive: s.last_activity_diff
}));

console.log('Browser usage:', browsers);
warning

Deleting sessions will immediately log out users from their current devices. Use this functionality carefully to avoid disrupting legitimate user activity.

X

Graph View