Skip to main content

Portal Login

Endpoints Summary

Method Path Swagger POST /portal_login/ Swagger ↗

The Portal Loginportal_login API enablesprovides 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 forare captiverequired portalbefore networks.granting Thisinternet endpoint handles user authentication flows, captures device information, and establishes network access sessions with configurable timeout parameters for WiFi hotspots and access control systems.access.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Portal Loginportal_login API category providesis essential functionalitydesigned for WiFi captive portal authenticationsystems systems.that Whenneed to authenticate users connectbefore to a WiFigranting network withaccess. a captive portal, thisThis API processeshandles theirthe logincritical attemptshandoff between access points, controllers, and establishesthe authenticatedauthentication sessions.platform.

Key Concepts:

  • Captive Portal AuthenticationFlow: Intercepts network traffic untilWhen users authenticate
connect to DeviceWiFi, Tracking:they're Capturesredirected MACto addressesan andauthentication IPpage informationbefore foraccessing accessthe controlinternet Session Management: EstablishesThe time-basedAPI accesscreates authenticated sessions with configurable timeoutstimeout periods NetworkMulti-device Support: Tracks individual devices by MAC address and assigns IP addresses Controller Integration: Works with access points and network controllers to manage access point configurations

Common Integration Scenarios:

  • Hotel WiFi login systems that requirerequiring room credentials
Coffee shop hotspots with social medianumber authentication Corporate guest networks with sponsoremail-based approval workflowslogin Public WiFi systemshotspots with terms of service acceptance Retail environmentslocations with customersocial registrationmedia portalslogin requirements

The APIportal_login handlesendpoint serves as the technical aspects of session establishment while allowing flexibility in authentication methodsgateway, processing user credentials and userdevice experienceinformation design.to establish authorized network sessions.

Endpoints

POST /portal_login/

Description: Executes a portal login operation to authenticate a user device and establish a network access session. This endpoint processes authentication data,data validatesfrom credentials,captive portals and creates an authorized sessionsessions with the network controller, enabling internet access for the requestingauthenticated device with configurable timeout parameters.device.

Use Cases:

  • Authenticate hotel guests using room numbercredentials andbefore lastgranting nameWiFi access
  • Process corporate visitor registration and create temporary network access
Handle social media login credentialsflows for public WiFi accesshotspots Validate corporate guest access with sponsor approval Register new users for retail WiFi with email verification Accept terms of service acceptance for publicretail hotspotlocation accessWiFi

Full URL Example:

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

Request Body Parameters:

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

RequestData BodyObject Structure: The data parameter should contain a JSON objectstring with the following authentication details,information:

Field Type Required Description uid string Yes Unique identifier for the user (email, username, room number, etc.) ap_mac string Yes MAC address of the access point handling the connection mac string Yes MAC address of the user's device information, and ip string Yes IP address assigned to the user's device original_url string No The original URL the user was trying to access controller_address string No IP address of the network controller session_timeout integer No Maximum session parameters.duration in seconds idle_timeout integer No Idle timeout period in seconds

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\ap_mac\":\"aa:bb:cc:dd:ee:ff\",\"ap_mac\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\":1800}3600}"
}'

Example Response:

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

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 originally 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'sauthenticated device ip string Yes IP address assigned to the user's device uid string Yes User identifier (email,used username,for or other reference)authentication controller_address string NoNetwork controller 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 duration in seconds before session expires (e.g., 1800 = 30 minutes)

Response Codes:

Status Description
201 Success - Portal login completed and session establishedsuccessfully
400 Bad Request - Invalid data format or missing required fields
401 Unauthorized - Invalid or missing API token
422 Unprocessable Entity - Authentication failed or deviceinvalid blockeduser credentials
500 Internal Server Error - PortalServer-side systemprocessing unavailableerror

Common Use Cases

Use Case 1: Hotel Guest WiFi Authentication

ProcessAuthenticate hotel guest loginguests using their room number and last name,name. establishingThe portal captures the guest's device information and creates a 24-hour session withthat 30-minuteexpires idleat timeoutcheckout fortime.

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

Use Case 2: CoffeeCorporate ShopGuest Social LoginNetwork

AuthenticateProcess customersvisitor throughregistration socialwhere mediaguests credentials,provide creatingtheir aemail 2-houraddress sessionand thataccept automaticallyterms expiresof whenservice inactivebefore foraccessing 15the minutes.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: CorporatePublic GuestWiFi Accesswith Social Login

ValidateHandle guestauthentication credentialsflows withwhere sponsorusers approval,log settingin upthrough restrictedsocial networkmedia platforms (Facebook, Google) to access withfree customWiFi in retail locations.

Implementation: Use the social media user ID as the uid and set appropriate session durationtimeouts basedfor onfair approvalusage level.policies.

Use Case 4: PublicEvent HotspotWiFi Terms AcceptanceManagement

ProcessManage termsWiFi access for conference attendees using registration codes or badge scan data, with sessions that expire at the end of serviceeach acceptanceday.

Implementation: Use attendee registration codes as the uid with daily session timeouts and controller integration for publicbandwidth 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.management.

Best Practices

Authentication Data Security:Format:

  • Always transmitensure authenticationthe data overparameter HTTPScontains properly escaped JSON strings
  • Validate andMAC sanitizeaddresses allare userin inputsthe correct format (aa:bb:cc:dd:ee:ff) before processingsending
  • ImplementInclude ratesession limitingtimeouts 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 upindefinite 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 abuseaccess

      Error Handling:

      • Provide clear error messages for authentication failures without revealing system details
      Implement retry logic with exponential backoff for temporary network failures (5xx errors) Validate user credentials before calling the API to minimize 422 responses Log failedauthentication attempts for security monitoring and troubleshooting

      NetworkSecurity Integration:Considerations:

      • EnsureNever yourlog portalor systemexpose canthe communicatefull 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 networkresource controllers Test timeout configurations with your specific network hardwareusage Monitor sessionAPI establishmentresponse success ratestimes and adjustimplement parameterstimeout ashandling neededin 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
          Back to top