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.
Make sure you generated the api_token on your store. More info in the API Authentication guide
Endpoint Reference
Endpoint | Method | Description |
---|---|---|
/integration-api/v1/auth-sessions | GET | List authentication sessions with optional filtering |
/integration-api/v1/auth-sessions/(id) | DELETE | Delete a specific authentication session |
/integration-api/v1/auth-sessions/users/(user_id) | DELETE | Delete 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
Parameter | Type | Description | Example |
---|---|---|---|
user_id | integer | Filter sessions by specific user ID | ?user_id=123 |
external_id | string | Filter sessions by specific user external ID | ?external_id=user-123 |
per_page | integer | Number of results per page (1-200, default: 100) | ?per_page=50 |
cursor | string | Pagination cursor for next page | ?cursor=eyJsYXN0X2FjdGl2aXR5Ijo... |
Response Fields
Field | Description | Type |
---|---|---|
CODE | Response status code | string |
data | Array of auth session objects | array |
pagination.per_page | Number of items per page | integer |
pagination.next_cursor | Cursor for next page (if available) | string/null |
pagination.has_more | Whether more pages are available | boolean |
Auth Session Object Fields
Field | Description | Type |
---|---|---|
id | Unique session identifier | string |
user_id | ID of the user who owns this session | integer |
user_email | Email of the user who owns this session | string |
user_external_id | External ID of the user who owns this session | string/null |
ip_address | IP address from which session was created | string |
session_data | Session information (web browser or mobile app details) | object |
last_activity | Last activity timestamp in ISO format | string |
last_activity_diff | Human-readable time since last activity | string |
session_expires_at | Session expiration timestamp in ISO format | string |
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
Code | Description |
---|---|
200 | Success |
422 | Validation error (invalid parameters) |
401 | Unauthorized (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
Parameter | Type | Description | Required |
---|---|---|---|
id | string | The session ID to delete | Yes |
Example Request
DELETE /integration-api/v1/auth-sessions/abc123def456ghi789
Example Response
{
"CODE": "success",
"message": "Session deleted successfully"
}
Response Codes
Code | Description |
---|---|
200 | Session deleted successfully |
404 | Session not found |
401 | Unauthorized (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
Parameter | Type | Description | Required |
---|---|---|---|
user_id | integer | The user ID whose sessions should be deleted | Yes |
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
Code | Description |
---|---|
200 | Sessions deleted successfully |
404 | User not found |
401 | Unauthorized (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
- Session Analysis
- Session Limit Management
- User Session Cleanup
// 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);
// Manage session limits for a user
const userId = 123;
const maxSessions = 3;
// Get all sessions for the user
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;
console.log(`User has ${sessions.length} active sessions`);
// If user exceeds session limit, remove oldest sessions
if (sessions.length > maxSessions) {
// Sort by last_activity (oldest first)
const sortedSessions = sessions.sort((a, b) =>
new Date(a.last_activity) - new Date(b.last_activity)
);
// Calculate how many sessions to remove
const sessionsToRemove = sessions.length - maxSessions;
const oldestSessions = sortedSessions.slice(0, sessionsToRemove);
// Delete oldest sessions
for (const session of oldestSessions) {
await fetch(`/integration-api/v1/auth-sessions/${session.id}`, {
method: 'DELETE',
headers: {
'X-User-Token': 'your-api-token'
}
});
console.log(`Deleted session: ${session.id} (last active: ${session.last_activity_diff})`);
}
}
// Remove all sessions for a specific user
const userId = 123;
const response = await fetch(`/integration-api/v1/auth-sessions/users/${userId}`, {
method: 'DELETE',
headers: {
'X-User-Token': 'your-api-token'
}
});
const result = await response.json();
console.log(`Deleted ${result.data.deleted_count} sessions for user ${userId}`);
Deleting sessions will immediately log out users from their current devices. Use this functionality carefully to avoid disrupting legitimate user activity.