Portal Login

The Portal Login API provides secureenables authentication functionalityand session management for accessingcaptive theportal GATE system portal.networks. This endpoint handles user authentication andflows, sessioncaptures management,device returning the necessary tokensinformation, and userestablishes informationnetwork access sessions with configurable timeout parameters for subsequentWiFi APIhotspots calls.and access control systems.

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

Authentication: ThisAll endpoint is used to obtain authentication tokens and does notendpoints require a Bearer token:

Authorization: Bearer <your-api-token>
itself.

---

Overview

The Portal Login API category containsprovides essential functionality for captive portal authentication systems. When users connect to a singleWiFi butnetwork crucialwith endpointa thatcaptive servesportal, asthis theAPI entryprocesses pointtheir forlogin userattempts authenticationand inestablishes theauthenticated GATEsessions.

system.

Key This endpoint is designed to:Concepts:

• Authenticate userCaptive credentialsPortal againstAuthentication: theIntercepts GATEnetwork systemtraffic until users authenticate
• Establish secureDevice Tracking: Captures MAC addresses and IP information for access control

Session Management: Establishes time-based access sessions forwith portalconfigurable accesstimeouts Return authenticationNetwork tokensIntegration: forWorks subsequentwith APIaccess requests Provide user profile informationpoints and permissionsnetwork after successful logincontrollers

UnlikeCommon otherIntegration APIScenarios:

endpoints

Hotel WiFi login systems that require authentication,room credentials Coffee shop hotspots with social media authentication Corporate guest networks with sponsor approval workflows Public WiFi systems with terms of service acceptance Retail environments with customer registration portals

The API handles the portaltechnical loginaspects endpointof issession publiclyestablishment accessiblewhile butallowing requiresflexibility validin authentication methods and user credentialsexperience in the request body. The response from a successful login typically includes access tokens, refresh tokens, user profile data, and session information that will be used for all subsequent authenticated requests.

This endpoint is essential for any application or service that needs to integrate with the GATE portal functionality, whether it's a web application, mobile app, or automated system requiring authenticated access.design.

---

Endpoints

POST /portal_login/

Description: Authenticates user credentials and establishesExecutes 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 providedrequesting login credentials against the GATE system and returns authentication tokens alongdevice with userconfigurable profiletimeout information upon successful authentication.parameters.

Use Cases:

• UserAuthenticate hotel guests using room number and last name

Process social media login credentials for webpublic applicationsWiFi integratingaccess Validate corporate guest access with GATEsponsor portalapproval MobileRegister appnew authenticationusers flowsfor retail WiFi with email verification AutomatedAccept systemterms authenticationof service for scheduledpublic taskshotspot Single sign-on (SSO) integration scenarios API client initialization requiring user contextaccess

Full URL Example:

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

Parameters:

Parameter	Type	In	Required	Description
data	string	body	Yes	JSON string containing user credentialsauthentication and device information for portal login parameters. Must include username/email and password at minimum.

Request Body Structure: The data parameter should contain a JSON stringobject with theauthentication followingdetails, structure:device information, and session parameters.

{
  "username": "user@example.com",
  "password": "user_password",
  "remember_me": true,
  "device_id": "unique_device_identifier"
}

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": "{\"username\uid\":\"user@example.guest@hotel.com\",\"password\mac\":\"secure_password\aa:bb:cc:dd:ee:ff\",\"remember_me\":true,\"device_id\ap_mac\":\"web_client_001\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:

{
  "success": true,
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user": {
    "id"page_id": 12345,
  "username"original_url": "user@example.https://google.com",
  "email"ap_mac": "user@example.11:22:33:44:55:66",
  "mac": "aa:bb:cc:dd:ee:ff",
  "ip": "192.168.1.100",
  "uid": "guest@hotel.com",
  "first_name"controller_address": "John"192.168.1.1",
  "last_name"session_timeout": "Doe",7200,
  "organization_id"idle_timeout": 789,
    "organization_name": "ACME Corporation",
    "role": "admin",
    "permissions": [
      "device_management",
      "user_management",
      "reporting"
    ],
    "last_login": "2024-01-15T10:30:00Z",
    "profile_complete": true
  },
  "session": {
    "session_id": "sess_abc123def456",
    "expires_at": "2024-01-15T14:30:00Z",
    "device_registered": true
  }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 - UserPortal authenticatedlogin successfully,completed and session createdestablished
400	Bad Request - Invalid requestdata format or missing required fields
401	Unauthorized - Invalid credentialsor providedmissing API token
403422	ForbiddenUnprocessable Entity - AccountAuthentication locked, suspended,failed or requiresdevice additional verification

429 Too Many Requests - Rate limit exceeded for login attemptsblocked 500 Internal Server Error - Server-sidePortal authenticationsystem errorunavailable

---

Common Use Cases

Use Case 1: WebHotel ApplicationGuest UserWiFi LoginAuthentication

ImplementProcess userhotel authenticationguest inlogin using room number and last name, establishing a web24-hour applicationsession thatwith needs30-minute toidle accesstimeout GATE portal features. After successful login, storefor the accessguest token for subsequent API calls and use the refresh token to maintain the session.network.

Use Case 2: MobileCoffee AppShop AuthenticationSocial Login

Authenticate mobilecustomers appthrough userssocial andmedia establishcredentials, persistentcreating sessionsa using2-hour devicesession identification.that Theautomatically remember_meexpires flagwhen andinactive device_idfor help15 maintain user sessions across app launches.minutes.

Use Case 3: AutomatedCorporate SystemGuest AuthenticationAccess

SetValidate guest credentials with sponsor approval, setting up automatedrestricted systemsnetwork oraccess backgroundwith servicescustom thatsession needduration to perform actionsbased on behalfapproval of a user account. Store credentials securely and handle token refresh automatically.level.

Use Case 4: APIPublic IntegrationHotspot TestingTerms Acceptance

DuringProcess developmentterms andof testing,service use this endpoint to obtain valid authentication tokensacceptance for testingpublic otherWiFi, APIestablishing endpointsbasic thatinternet requireaccess authentication.with standard timeout policies.

Use Case 5: Multi-OrganizationRetail AccessCustomer Registration

ForHandle usersnew customer registration with accessemail toverification, multiplecreating organizations,personalized usesessions thewith returnedloyalty organizationprogram information to determine available features and data access levels within the GATE system.integration.

---

Best Practices

Authentication Data Security:

• Always

  Securetransmit Credentialauthentication Handling: Never log or store user passwords in plain text. Ensure credentials are transmitteddata over HTTPS

Validate and handlesanitize themall securelyuser ininputs yourbefore application. processing Implement

Tokenrate Management:limiting to prevent brute force attacks

Store accesssensitive tokenscredentials securely and implementfollow automaticdata refreshprotection logicregulations using the

Session refresh token before the access token expires.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:

Implement

comprehensiveProvide clear error handlingmessages for differentauthentication responsefailures codes,without especiallyrevealing forsystem account lockouts (403) and rate limiting (429). details Implement

Deviceretry Management: Use consistent device_id values for the same client to helplogic with session management and security monitoring.

Session Monitoring: Track session expiration times and implement logout functionality that properly invalidates tokens when users end their sessions.

Rate Limit Awareness: Implement exponential backoff for failedtemporary login attempts to avoid triggering rate limits, especially in automated systems.

failures

Security Logging: Log authenticationfailed events (successful logins, failures, suspicious activities)attempts for security monitoring and compliance purposes.

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

---