Portal Login

Base URL: https://gate.zequenze.com/api/v1

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

Key Concepts:

Captive Portal Authentication: Intercepts network traffic until users authenticate
Device Tracking: Captures MAC addresses and IP information for access control
Session Management: Establishes time-based access sessions with configurable timeouts
Network Integration: Works with access points and network controllers

Common Integration Scenarios:

The API handles the technical aspects of session establishment while allowing flexibility in authentication methods and user experience design.

Endpoints

POST /portal_login/

Description: Executes a portal login operation to authenticate a user and establish a network access session. This endpoint processes authentication data, validates credentials, and creates an authorized session for the requesting device with configurable timeout parameters.

Use Cases:

Authenticate hotel guests using room number and last name
Process social media login credentials for public WiFi access
Validate corporate guest access with sponsor approval
Register new users for retail WiFi with email verification
Accept terms of service for public hotspot access

Full URL Example:

https://gate.zequenze.com/api/v1/portal_login/

Parameters:

Parameter	Type	In	Required	Description
data	string	body	Yes	JSON string containing authentication and device information for portal login

Request Body Structure: The data parameter should contain a JSON object with authentication details, device information, and session parameters.

cURL Example:

curl -X POST "https://gate.zequenze.com/api/v1/portal_login/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": "{\"uid\":\"guest@hotel.com\",\"mac\":\"aa:bb:cc:dd:ee:ff\",\"ap_mac\":\"11:22:33:44:55:66\",\"ip\":\"192.168.1.100\",\"original_url\":\"https://google.com\",\"controller_address\":\"192.168.1.1\",\"session_timeout\":7200,\"idle_timeout\":1800}"
  }'

Example Response:

{
  "page_id": 12345,
  "original_url": "https://google.com",
  "ap_mac": "11:22:33:44:55:66",
  "mac": "aa:bb:cc:dd:ee:ff",
  "ip": "192.168.1.100",
  "uid": "guest@hotel.com",
  "controller_address": "192.168.1.1",
  "session_timeout": 7200,
  "idle_timeout": 1800
}

Response Fields:

Field	Type	Required	Description
page_id	integer	Yes	Unique identifier for this portal session page
original_url	string	No	The URL the user was trying to access when redirected to the portal
ap_mac	string	Yes	MAC address of the access point handling this connection
mac	string	Yes	MAC address of the user's device
ip	string	Yes	IP address assigned to the user's device
uid	string	Yes	User identifier (email, username, or other reference)
controller_address	string	No	IP address of the network controller managing the session
session_timeout	integer	No	Maximum session duration in seconds (e.g., 7200 = 2 hours)
idle_timeout	integer	No	Idle timeout in seconds before session expires (e.g., 1800 = 30 minutes)

Response Codes:

Status	Description
201	Success - Portal login completed and session established
400	Bad Request - Invalid data format or missing required fields
401	Unauthorized - Invalid or missing API token
422	Unprocessable Entity - Authentication failed or device blocked
500	Internal Server Error - Portal system unavailable

Common Use Cases

Use Case 1: Hotel Guest WiFi Authentication

Process hotel guest login using room number and last name, establishing a 24-hour session with 30-minute idle timeout for the guest network.

Use Case 2: Coffee Shop Social Login

Authenticate customers through social media credentials, creating a 2-hour session that automatically expires when inactive for 15 minutes.

Use Case 3: Corporate Guest Access

Validate guest credentials with sponsor approval, setting up restricted network access with custom session duration based on approval level.

Use Case 4: Public Hotspot Terms Acceptance

Process terms of service acceptance for public WiFi, establishing basic internet access with standard timeout policies.

Use Case 5: Retail Customer Registration

Handle new customer registration with email verification, creating personalized sessions with loyalty program integration.

Best Practices

Authentication Data Security:

Always transmit authentication data over HTTPS
Validate and sanitize all user inputs before processing
Implement rate limiting to prevent brute force attacks
Store sensitive credentials securely and follow data protection regulations

Session Management:

Set appropriate session timeouts based on your use case (hotels may need 24 hours, coffee shops may need 2-4 hours)
Configure idle timeouts to free up network resources (typically 15-30 minutes)
Monitor active sessions to prevent abuse and ensure fair usage

Device Tracking:

Use MAC addresses for device identification but be aware of MAC randomization on modern devices
Combine MAC addresses with other identifiers for more reliable tracking
Implement device limits per user account to prevent sharing abuse

Error Handling:

Provide clear error messages for authentication failures without revealing system details
Implement retry logic with exponential backoff for temporary failures
Log failed attempts for security monitoring and troubleshooting

Network Integration:

Ensure your portal system can communicate with network controllers
Test timeout configurations with your specific network hardware
Monitor session establishment success rates and adjust parameters as needed