Skip to main content

Portal Login

The Portal Login API provides secure authentication functionality for accessing the GATE system portal. This endpoint handles user authentication and session management, returning the necessary tokens and user information for subsequent API calls.

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

Authentication: This endpoint is used to obtain authentication tokens and does not require a Bearer token itself.

Overview

The Portal Login API category contains a single but crucial endpoint that serves as the entry point for user authentication in the GATE system. This endpoint is designed to:

  • Authenticate user credentials against the GATE system
  • Establish secure sessions for portal access
  • Return authentication tokens for subsequent API requests
  • Provide user profile information and permissions after successful login

Unlike other API endpoints that require authentication, the portal login endpoint is publicly accessible but requires valid user credentials 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.

Endpoints

POST /portal_login/

Description: Authenticates user credentials and establishes a portal session. This endpoint validates the provided login credentials against the GATE system and returns authentication tokens along with user profile information upon successful authentication.

Use Cases:

  • User login for web applications integrating with GATE portal
  • Mobile app authentication flows
  • Automated system authentication for scheduled tasks
  • Single sign-on (SSO) integration scenarios
  • API client initialization requiring user context

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 credentials and login parameters. Must include username/email and password at minimum.

Request Body Structure: The data parameter should contain a JSON string with the following structure:

{
  "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 "Content-Type: application/json" \
  -d '{
    "data": "{\"username\":\"user@example.com\",\"password\":\"secure_password\",\"remember_me\":true,\"device_id\":\"web_client_001\"}"
  }'

Example Response:

{
  "success": true,
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user": {
    "id": 12345,
    "username": "user@example.com",
    "email": "user@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "organization_id": 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
  }
}

Response Codes:

Status Description
201 Success - User authenticated successfully, session created
400 Bad Request - Invalid request format or missing required fields
401 Unauthorized - Invalid credentials provided
403 Forbidden - Account locked, suspended, or requires additional verification
429 Too Many Requests - Rate limit exceeded for login attempts
500 Internal Server Error - Server-side authentication error

Common Use Cases

Use Case 1: Web Application User Login

Implement user authentication in a web application that needs to access GATE portal features. After successful login, store the access token for subsequent API calls and use the refresh token to maintain the session.

Use Case 2: Mobile App Authentication

Authenticate mobile app users and establish persistent sessions using device identification. The remember_me flag and device_id help maintain user sessions across app launches.

Use Case 3: Automated System Authentication

Set up automated systems or background services that need to perform actions on behalf of a user account. Store credentials securely and handle token refresh automatically.

Use Case 4: API Integration Testing

During development and testing, use this endpoint to obtain valid authentication tokens for testing other API endpoints that require authentication.

Use Case 5: Multi-Organization Access

For users with access to multiple organizations, use the returned organization information to determine available features and data access levels within the GATE system.

Best Practices

  • Secure Credential Handling: Never log or store user passwords in plain text. Ensure credentials are transmitted over HTTPS and handle them securely in your application.

  • Token Management: Store access tokens securely and implement automatic refresh logic using the refresh token before the access token expires.

  • Error Handling: Implement comprehensive error handling for different response codes, especially for account lockouts (403) and rate limiting (429).

  • Device Management: Use consistent device_id values for the same client to help 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 failed login attempts to avoid triggering rate limits, especially in automated systems.

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

Back to top