Sessions API

Manage user sessions, validate sessions, and control active sessions.

---

Base URL

https://your-instance-name.pubflow.com

---

Validate Session (Bridge API)

Validate a session and get a trust token. This endpoint is used by your backend (Flowfull) to validate user sessions.

Endpoint

POST /bridge/validate

Headers

Content-Type: application/json
X-Bridge-Secret: your_bridge_secret

Request Body

{
  "session_id": "ses_xyz123456",
  "ip_address": "192.168.1.1",
  "user_agent": "Mozilla/5.0...",
  "device_id": "device_abc123"
}

Parameters

Field	Type	Required	Description
session_id	string	Yes	Session ID to validate
ip_address	string	Conditional*	Client's IP address
user_agent	string	Conditional**	Client's user agent
device_id	string	Conditional***	Device identifier

*Required for STANDARD, ADVANCED, STRICT modes
**Required for STRICT mode
***Required for ADVANCED, STRICT modes

Response

{
  "success": true,
  "data": {
    "valid": true,
    "trust_token": "v4.public.eyJ1c2VyX2lkIjoidXNyXzEyMzQ1Njc4OTAiLCJzZXNzaW9uX2lkIjoic2VzX3h5ejEyMzQ1NiIsImVtYWlsIjoidXNlckBleGFtcGxlLmNvbSIsIm5hbWUiOiJKb2huIERvZSIsImV4cCI6MTczMzU3NDAwMCwiaWF0IjoxNzMzNTcwNDAwfQ",
    "user": {
      "id": "usr_1234567890",
      "email": "user@example.com",
      "name": "John",
      "last_name": "Doe",
      "username": "johndoe",
      "is_verified": true
    },
    "session": {
      "id": "ses_xyz123456",
      "expires_at": "2025-12-14T10:00:00Z",
      "created_at": "2025-12-07T10:00:00Z"
    }
  }
}

Trust Token Contents

The trust token is a PASETO token containing:

{
  "user_id": "usr_1234567890",
  "session_id": "ses_xyz123456",
  "email": "user@example.com",
  "name": "John Doe",
  "exp": 1733574000,
  "iat": 1733570400
}

Error Responses

// Invalid session
{
  "success": false,
  "error": "Invalid or expired session"
}

// IP mismatch (STANDARD/ADVANCED/STRICT)
{
  "success": false,
  "error": "IP address mismatch"
}

// Device mismatch (ADVANCED/STRICT)
{
  "success": false,
  "error": "Device ID mismatch"
}

// User agent mismatch (STRICT)
{
  "success": false,
  "error": "User agent mismatch"
}

// Invalid bridge secret
{
  "success": false,
  "error": "Unauthorized"
}

Example (Backend)

// In your Flowfull backend
async function validateSession(sessionId: string, req: Request) {
  const response = await fetch('https://your-instance.pubflow.com/bridge/validate', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Bridge-Secret': process.env.BRIDGE_SECRET!,
    },
    body: JSON.stringify({
      session_id: sessionId,
      ip_address: req.headers.get('x-forwarded-for') || req.ip,
      user_agent: req.headers.get('user-agent'),
      device_id: req.headers.get('x-device-id'),
    }),
  });

  const data = await response.json();
  
  if (!data.success || !data.data.valid) {
    throw new Error('Invalid session');
  }

  // Cache the trust token for 5 minutes
  await cache.set(`trust_token:${sessionId}`, data.data.trust_token, 300);

  return data.data.user;
}

---

Get User Sessions

Get all active sessions for the authenticated user.

Endpoint

GET /auth/sessions

Headers

X-Session-ID: ses_xyz123456

Response

{
  "success": true,
  "data": [
    {
      "id": "ses_xyz123456",
      "device_id": "device_abc123",
      "ip_address": "192.168.1.1",
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
      "created_at": "2025-12-07T10:00:00Z",
      "expires_at": "2025-12-14T10:00:00Z",
      "is_current": true
    },
    {
      "id": "ses_def456789",
      "device_id": "device_xyz789",
      "ip_address": "192.168.1.2",
      "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0...)...",
      "created_at": "2025-12-06T15:30:00Z",
      "expires_at": "2025-12-13T15:30:00Z",
      "is_current": false
    }
  ]
}

---

Revoke Session

Revoke a specific session (logout from a specific device).

Endpoint

DELETE /auth/sessions/:session_id

Headers

X-Session-ID: ses_xyz123456

Parameters

Field	Type	Required	Description
session_id	string	Yes	Session ID to revoke (in URL)

Response

{
  "success": true,
  "message": "Session revoked successfully"
}

Example

// Revoke a specific session
await fetch('https://your-instance.pubflow.com/auth/sessions/ses_def456789', {
  method: 'DELETE',
  headers: {
    'X-Session-ID': 'ses_xyz123456', // Current session
  },
});

---

Revoke All Sessions

Revoke all sessions except the current one (logout from all other devices).

Endpoint

DELETE /auth/sessions

Headers

X-Session-ID: ses_xyz123456

Response

{
  "success": true,
  "message": "All other sessions revoked",
  "data": {
    "revoked_count": 3
  }
}

---

Validation Modes

Flowless supports three validation modes configured via environment variable:

STANDARD (Default)

Validates:

• ✅ Session ID
• ✅ IP address

VALIDATION_MODE=STANDARD

ADVANCED

Validates:

• ✅ Session ID
• ✅ IP address
• ✅ Device ID

VALIDATION_MODE=ADVANCED

STRICT

Validates:

• ✅ Session ID
• ✅ IP address
• ✅ Device ID
• ✅ User agent

VALIDATION_MODE=STRICT

TIP

Use STANDARD for most applications. Use ADVANCED or STRICT for high-security applications.

---

Session Security

Session ID Format

• Unhashed: ses_ prefix (e.g., ses_xyz123456)
• Hashed: hashed_ses_ prefix (stored in database)
• Algorithm: SHA-256

Session Expiration

• Default: 7 days
• Configurable: 1 hour to 30 days
• Auto-cleanup: Expired sessions are automatically deleted

Session Binding

Sessions can be bound to:

• IP Address: Prevents session hijacking from different IPs
• Device ID: Prevents session use on different devices
• User Agent: Prevents session use from different browsers/apps

---

Next Steps

• Authentication API - Login and registration
• Users API - User management
• Security Best Practices - Secure your sessions