Portal Login

Endpoints Summary

The portal_login API provides functionality for managing captive portal authentication flows, allowing access points to redirect users through a centralized authentication system. This endpoint is primarily used in WiFi network environments where user authentication and session management are required before granting internet access.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The portal_login API category is designed for WiFi captive portal systems that need to authenticate users before granting network access. This API handles the critical handoff between access points, controllers, and the authentication platform.

Key Concepts:

• Captive Portal Flow: When users connect to WiFi, they're redirected to an authentication page before accessing the internet
• Session Management: The API creates authenticated sessions with configurable timeout periods
• Multi-device Support: Tracks individual devices by MAC address and assigns IP addresses
• Controller Integration: Works with network controllers to manage access point configurations

Common Integration Scenarios:

• Hotel WiFi systems requiring room number authentication
• Corporate guest networks with email-based login
• Public WiFi hotspots with terms of service acceptance
• Retail locations with social media login requirements

The portal_login endpoint serves as the authentication gateway, processing user credentials and device information to establish authorized network sessions.

Endpoints

POST /portal_login/

Description: Executes a portal login operation to authenticate a user device and establish a network session. This endpoint processes authentication data from captive portals and creates authorized sessions with the network controller, enabling internet access for the authenticated device.

Use Cases:

• Authenticate hotel guests using room credentials before granting WiFi access
• Process corporate visitor registration and create temporary network access
• Handle social media login flows for public WiFi hotspots
• Validate terms of service acceptance for retail location WiFi

Full URL Example:

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

Request Body Parameters:

Data Object Structure: The data parameter should contain a JSON string with the following authentication information:

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\",\"ap_mac\":\"aa:bb:cc:dd:ee:ff\",\"mac\":\"11:22:33:44:55:66\",\"ip\":\"192.168.1.100\",\"original_url\":\"https://www.google.com\",\"controller_address\":\"192.168.1.1\",\"session_timeout\":3600,\"idle_timeout\":1800}"
  }'

Example Request Body:

{
  "data": "{\"uid\":\"room_401\",\"ap_mac\":\"aa:bb:cc:dd:ee:ff\",\"mac\":\"11:22:33:44:55:66\",\"ip\":\"192.168.1.100\",\"original_url\":\"https://www.example.com\",\"controller_address\":\"192.168.1.1\",\"session_timeout\":7200,\"idle_timeout\":3600}"
}

Example Response:

{
  "page_id": 12345,
  "original_url": "https://www.example.com",
  "ap_mac": "aa:bb:cc:dd:ee:ff",
  "mac": "11:22:33:44:55:66",
  "ip": "192.168.1.100",
  "uid": "room_401",
  "controller_address": "192.168.1.1",
  "session_timeout": 7200,
  "idle_timeout": 3600
}

Response Fields:

Response Codes:

Common Use Cases

Use Case 1: Hotel Guest Authentication

Authenticate hotel guests using their room number and last name. The portal captures the guest's device information and creates a session that expires at checkout time.

Implementation: Use the guest's room number as the uid and set session_timeout based on their stay duration.

Use Case 2: Corporate Guest Network

Process visitor registration where guests provide their email address and accept terms of service before accessing the corporate guest WiFi.

Implementation: Use the guest's email as the uid and include the original destination URL to redirect them after authentication.

Use Case 3: Public WiFi with Social Login

Handle authentication flows where users log in through social media platforms (Facebook, Google) to access free WiFi in retail locations.

Implementation: Use the social media user ID as the uid and set appropriate session timeouts for fair usage policies.

Use Case 4: Event WiFi Management

Manage WiFi access for conference attendees using registration codes or badge scan data, with sessions that expire at the end of each day.

Implementation: Use attendee registration codes as the uid with daily session timeouts and controller integration for bandwidth management.

Best Practices

Data Format:

• Always ensure the data parameter contains properly escaped JSON strings
• Validate MAC addresses are in the correct format (aa:bb:cc:dd:ee:ff) before sending
• Include session timeouts to prevent indefinite network access

Error Handling:

• Implement retry logic for temporary network failures (5xx errors)
• Validate user credentials before calling the API to minimize 422 responses
• Log authentication attempts for security monitoring and troubleshooting

Security Considerations:

• Never log or expose the full API token in client-side code
• Use HTTPS for all API communications to protect authentication data
• Implement rate limiting to prevent abuse of the authentication endpoint

Performance Tips:

• Cache successful authentication responses to avoid duplicate API calls
• Set appropriate session timeouts to balance user experience with resource usage
• Monitor API response times and implement timeout handling in your application

Session Management:

• Store the returned page_id for session tracking and potential logout operations
• Respect the configured timeout values and handle session expiration gracefully
• Consider implementing session renewal for long-term users