Skip to main content

Device App User Authenticate

The device app user authentication endpoint provides 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 applications 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 JSON string containing user credentials (username, password) and optional device information (device_id, app_version, platform)

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

{
  "username": "user@example.com",
  "password": "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 (Failed Authentication):

{
  "status": "error",
  "message": "Invalid credentials",
  "error_code": "AUTH_FAILED",
  "attempts_remaining": 2,
  "lockout_time": null
}

Response Codes:

Status Description
201 Created - Authentication successful, tokens generated
400 Bad Request - Invalid data format or missing required fields
401 Unauthorized - Invalid credentials or authentication failed
403 Forbidden - Account locked or suspended
429 Too Many 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 Credential Handling: Always transmit credentials over HTTPS and never log 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 Limiting: Implement client-side rate limiting to prevent excessive authentication attempts. The API may return 429 status codes if too many requests are made in a short period.

  • Error Handling: Always handle authentication failures gracefully by checking the error_code field and providing appropriate user feedback. Monitor attempts_remaining to warn users before account lockout.

  • Device Information: Include accurate device information in the request data to help with security monitoring 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