Skip to main content

Device App User Authenticate

AuthenticateThe device app usersuser byauthentication validatingendpoint theirprovides credentials.secure credential validation for mobile applications and devices connecting to the GATE API. This endpoint verifies user login credentials and returns authentication tokens or status information, enabling secure access to protected resources within the GATE ecosystem.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The device app user authenticate API category is specifically designed for mobile applications and IoT devices that need to validate user credentials against the GATE authentication system. This endpoint serves as the primary authentication gateway for device-based applications, handling secure login processes and credential verification.

This authentication system is typically used when:

    Mobile applications need to authenticate users before granting access to device management features IoT devices require user validation before allowing configuration changes Third-party applications need to verify user credentials through the GATE system Device registration processes require user authentication as part of the setup flow

    The authentication process follows industry-standard security practices, ensuring that user credentials are validated securely while providing the necessary tokens or status information for subsequent API calls. This endpoint works in conjunction with other GATE API endpoints by providing the authentication foundation required for accessing protected resources.

    Endpoints

    POST /device_app_user_authenticate/

    Description: Validates user credentials for device app accessapplications and returns authentication status. This endpoint processes login requests from mobile apps and devices, verifying username/password combinations or other credential types against the GATE user database. Upon successful validation, it provides authentication tokens or session information needed for accessing protected API endpoints.

    Use Cases:

      Mobile app login screen credential validation IoT device user authentication during initial setup Third-party application integration requiring user verification Multi-factor authentication workflows for device access Session token generation for authenticated device sessions

      Full URL Example:

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

      Parameters:

      Parameter Type In Required Description
      data string body Yes UserJSON credentialstring datacontaining foruser authenticationcredentials (username, password) and optional device information (device_id, app_version, platform)

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

      POST /api/v1/device_app_user_authenticate/
Content-Type: application/json
Authorization: Bearer <your-api-token>

{
  "username": "john.doe"user@example.com",
  "password": "securePassword123"secure_password",
  "device_id": "device_12345",
  "app_version": "2.1.0",
  "platform": "iOS"
}

      cURL Example:

      curl -X POST "https://gate.zequenze.com/api/v1/device_app_user_authenticate/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": "{\"username\":\"user@example.com\",\"password\":\"secure_password\",\"device_id\":\"mobile_device_001\",\"app_version\":\"2.1.0\",\"platform\":\"iOS\"}"
  }'

      Example Response (Success):

      {
  "status": "success",
  "message": "Authentication successful",
  "user_id": 12345,
  "username": "user@example.com",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
  "token_expires_at": "2024-01-15T22:30:00Z",
  "user_permissions": [
    "device_read",
    "device_configure",
    "inventory_view"
  ],
  "device_registered": true,
  "session_id": "sess_abc123def456"
}

      Example Response:Response (Failed Authentication):

      {
  "authenticated": true,
  "user_id"status": "user_67890"error",
  "username"message": "john.doe"Invalid credentials",
  "token"error_code": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."AUTH_FAILED",
  "expires_at"attempts_remaining": "2024-01-15T14:30:00Z",2,
  "permissions"lockout_time": [
    "device_access",
    "app_usage"
  ]null
}

      Response Codes:

      Status Description
      201 Created - Authentication successfulsuccessful, tokens generated
      400 Bad Request - Invalid credentialsdata format or malformedmissing requestrequired fields
      401 Unauthorized - invalidInvalid APIcredentials tokenor authentication failed
      403 Forbidden - Account locked or suspended 429 Too manyMany Requests - Rate limit exceeded for authentication attempts 500 Internal Server Error - Server-side authentication system error

      Common Use Cases

      Use Case 1: Mobile App Login

      When users open your mobile application, use this endpoint to validate their credentials during the login process. The returned access token can then be used for all subsequent API calls, while the refresh token allows for seamless session renewal.

      Use Case 2: IoT Device Setup

      During the initial configuration of IoT devices, users need to authenticate to associate the device with their account. This endpoint validates the user's credentials and confirms they have permission to register new devices.

      Use Case 3: Third-Party Integration

      When integrating with external systems that need to authenticate GATE users, this endpoint provides a secure way to validate credentials without exposing the main authentication system directly.

      Use Case 4: Session Management

      For applications that need to maintain long-running sessions, this endpoint can be used to validate credentials and establish session tokens that can be refreshed as needed.

      Use Case 5: Multi-Device Authentication

      When users access the system from multiple devices, this endpoint helps manage authentication across different platforms while maintaining security and tracking device-specific access.

      Best Practices

      • Secure transmissionCredential Handling:: Always usetransmit credentials over HTTPS whenand transmittingnever credentialslog or store passwords in plain text. The data parameter should contain properly escaped JSON strings.

      • Token Management: Store the returned access tokens securely on the device using appropriate secure storage mechanisms (Keychain on iOS, Keystore on Android). Implement automatic token refresh using the refresh token before the access token expires.

      Rate limitingLimiting:: Implement client-side rate limiting to avoidprevent hittingexcessive theauthentication attempts. The API may return 429 status codes if too many requests are made in a short period.

      Token management: Store returned authentication tokens securely and refresh before expiration

      Error handlingHandling:: HandleAlways handle authentication failures gracefully withby checking the error_code field and providing appropriate user feedbackfeedback. Monitor attempts_remaining to warn users before account lockout.

      Device trackingInformation:: Include uniqueaccurate device identifiersinformation in the request data to supporthelp device-specificwith authenticationsecurity policiesmonitoring and device management. This information can be used for identifying suspicious login attempts.

      Session Security: Treat session tokens as sensitive data and implement appropriate logout mechanisms that invalidate tokens when users sign out of the application.

      Back to top