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

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
user_agent_info	Parsed browser and device information	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",
            "user_agent_info": {
                "browser": "Chrome",
                "device": "Desktop",
                "os": "macOS"
            },
            "last_activity": "2023-12-29T10:00:00",
            "last_activity_diff": "10 minutes ago",
            "session_expires_at": "2023-12-29T12:00: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)

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 Limit Management

// 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})`);
    }
}

User Session Cleanup

// 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}`);

warning

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