Skip to content

Latest commit

 

History

History
427 lines (363 loc) · 9.62 KB

sessions.md

File metadata and controls

427 lines (363 loc) · 9.62 KB
Raw

Session Management API

Endpoints Overview

  • GET /api/sessions - List all user sessions
  • GET /api/sessions/active - List active sessions
  • GET /api/sessions/{uuid} - Get session details
  • PATCH /api/sessions/{uuid}/renew - Renew session
  • DELETE /api/sessions/{uuid}/end - End session
  • PATCH /api/sessions/{uuid}/block - Block session
  • PATCH /api/sessions/{uuid}/unblock - Unblock session
  • POST /api/sessions/signout - Sign out from all sessions

Endpoint Details

List All Sessions

Retrieve all sessions for the authenticated user.

GET /api/sessions

cURL Example

curl -X GET "http://your-app.com/api/sessions" \
  -H "Authorization: Bearer your-token" \
  -H "Accept: application/json"

Axios Example

const response = await axios.get('/api/sessions', {
    headers: {
        'Authorization': `Bearer ${token}`,
        'Accept': 'application/json'
    }
});

Guzzle Example

$response = $client->get('/api/sessions');
$sessions = json_decode($response->getBody(), true);

Success Response (200)

{
    "data": [
        {
            "uuid": "98765432-fedc-ba98-7654-321fedcba987",
            "ip": "192.168.1.1",
            "location": {
                "ip": "192.168.1.1",
                "hostname": "host.example.com",
                "country": "ES",
                "region": "Madrid",
                "city": "Madrid",
                "postal": "28001",
                "latitude": "40.4168",
                "longitude": "-3.7038",
                "timezone": "Europe/Madrid",
                "label": "28001 Madrid, Madrid, ES"
            },
            "status": "active",
            "last_activity_at": "2024-10-27T15:45:00Z",
            "started_at": "2024-10-27T14:30:00Z",
            "finished_at": null,
            "device": {
                "uuid": "01234567-89ab-cdef-0123-456789abcdef",
                "status": "verified",
                "browser": {
                    "name": "Chrome",
                    "version": {
                        "major": "118",
                        "minor": "0",
                        "patch": "0"
                    }
                }
            }
        }
    ]
}

List Active Sessions

Retrieve only active sessions for the authenticated user.

GET /api/sessions/active

cURL Example

curl -X GET "http://your-app.com/api/sessions/active" \
  -H "Authorization: Bearer your-token" \
  -H "Accept: application/json"

Axios Example

const response = await axios.get('/api/sessions/active', {
    headers: {
        'Authorization': `Bearer ${token}`,
        'Accept': 'application/json'
    }
});

Guzzle Example

$response = $client->get('/api/sessions/active');

Success Response (200)

{
    "data": [
        {
            "uuid": "98765432-fedc-ba98-7654-321fedcba987",
            "ip": "192.168.1.1",
            "location": {
                "ip": "192.168.1.1",
                "hostname": "host.example.com",
                "country": "ES",
                "region": "Madrid",
                "city": "Madrid",
                "postal": "28001",
                "latitude": "40.4168",
                "longitude": "-3.7038",
                "timezone": "Europe/Madrid",
                "label": "28001 Madrid, Madrid, ES"
            },
            "status": "active",
            "last_activity_at": "2024-10-27T15:45:00Z",
            "started_at": "2024-10-27T14:30:00Z",
            "finished_at": null,
            "device": {
                "uuid": "01234567-89ab-cdef-0123-456789abcdef",
                "status": "verified"
            }
        }
    ]
}

Get Session Details

Retrieve detailed information about a specific session.

GET /api/sessions/{uuid}

cURL Example

curl -X GET "http://your-app.com/api/sessions/98765432-fedc-ba98-7654-321fedcba987" \
  -H "Authorization: Bearer your-token" \
  -H "Accept: application/json"

Axios Example

const response = await axios.get(`/api/sessions/${sessionUuid}`, {
    headers: {
        'Authorization': `Bearer ${token}`,
        'Accept': 'application/json'
    }
});

Guzzle Example

$response = $client->get("/api/sessions/{$sessionUuid}");

Success Response (200)

{
    "data": {
        "uuid": "98765432-fedc-ba98-7654-321fedcba987",
        "ip": "192.168.1.1",
        "location": {
            "ip": "192.168.1.1",
            "hostname": "host.example.com",
            "country": "ES",
            "region": "Madrid",
            "city": "Madrid",
            "postal": "28001",
            "latitude": "40.4168",
            "longitude": "-3.7038",
            "timezone": "Europe/Madrid",
            "label": "28001 Madrid, Madrid, ES"
        },
        "status": "active",
        "last_activity_at": "2024-10-27T15:45:00Z",
        "started_at": "2024-10-27T14:30:00Z",
        "finished_at": null,
        "device": {
            "uuid": "01234567-89ab-cdef-0123-456789abcdef",
            "status": "verified",
            "browser": {
                "name": "Chrome",
                "version": {
                    "major": "118",
                    "minor": "0",
                    "patch": "0"
                }
            }
        },
        "metadata": {}
    }
}

Renew Session

Update the last activity timestamp of a session.

PATCH /api/sessions/{uuid}/renew

cURL Example

curl -X PATCH "http://your-app.com/api/sessions/98765432-fedc-ba98-7654-321fedcba987/renew" \
  -H "Authorization: Bearer your-token" \
  -H "Accept: application/json"

Axios Example

const response = await axios.patch(`/api/sessions/${sessionUuid}/renew`, {}, {
    headers: {
        'Authorization': `Bearer ${token}`,
        'Accept': 'application/json'
    }
});

Success Response (200)

{
    "message": "Session renewed successfully"
}

Block/Unblock Session

Control session access through blocking/unblocking.

PATCH /api/sessions/{uuid}/block
PATCH /api/sessions/{uuid}/unblock

cURL Examples

# Block session
curl -X PATCH "http://your-app.com/api/sessions/98765432-fedc-ba98-7654-321fedcba987/block" \
  -H "Authorization: Bearer your-token" \
  -H "Accept: application/json"

# Unblock session
curl -X PATCH "http://your-app.com/api/sessions/98765432-fedc-ba98-7654-321fedcba987/unblock" \
  -H "Authorization: Bearer your-token" \
  -H "Accept: application/json"

Axios Examples

// Block session
const blockResponse = await axios.patch(`/api/sessions/${sessionUuid}/block`, {}, {
    headers: {
        'Authorization': `Bearer ${token}`,
        'Accept': 'application/json'
    }
});

// Unblock session
const unblockResponse = await axios.patch(`/api/sessions/${sessionUuid}/unblock`, {}, {
    headers: {
        'Authorization': `Bearer ${token}`,
        'Accept': 'application/json'
    }
});

Success Responses (200)

// Block
{
    "message": "Session blocked successfully"
}

// Unblock
{
    "message": "Session unblocked successfully"
}

End Session

Terminate a specific session.

DELETE /api/sessions/{uuid}/end

cURL Example

curl -X DELETE "http://your-app.com/api/sessions/98765432-fedc-ba98-7654-321fedcba987/end" \
  -H "Authorization: Bearer your-token" \
  -H "Accept: application/json"

Axios Example

const response = await axios.delete(`/api/sessions/${sessionUuid}/end`, {
    headers: {
        'Authorization': `Bearer ${token}`,
        'Accept': 'application/json'
    }
});

Success Response (200)

{
    "message": "Session ended successfully"
}

Sign Out from All Sessions

End all active sessions for the current user.

POST /api/sessions/signout

cURL Example

curl -X POST "http://your-app.com/api/sessions/signout" \
  -H "Authorization: Bearer your-token" \
  -H "Accept: application/json"

Axios Example

const response = await axios.post('/api/sessions/signout', {}, {
    headers: {
        'Authorization': `Bearer ${token}`,
        'Accept': 'application/json'
    }
});

Success Response (200)

{
    "message": "Signout successful"
}

Error Handling

All endpoints may return these common errors:

Session Locked (423)

{
    "message": "Session locked"
}

Rate Limited (429)

{
    "message": "Too Many Attempts.",
    "retry_after": 60
}

Usage Examples

Session Security Management Flow

async function manageSessionSecurity(sessionUuid) {
    try {
        // Get session details
        const sessionResponse = await axios.get(`/api/sessions/${sessionUuid}`);
        const session = sessionResponse.data.data;
        
        // Check location
        if (isLocationSuspicious(session.location)) {
            // Block session
            await axios.patch(`/api/sessions/${sessionUuid}/block`);
            return;
        }
        
        // Check inactivity
        const inactivityThreshold = 30 * 60 * 1000; // 30 minutes
        const lastActivity = new Date(session.last_activity_at);
        if (Date.now() - lastActivity > inactivityThreshold) {
            // End session
            await axios.delete(`/api/sessions/${sessionUuid}/end`);
            return;
        }
        
        // Renew active session
        await axios.patch(`/api/sessions/${sessionUuid}/renew`);
        
    } catch (error) {
        handleApiError(error);
    }
}

Next Steps