Skip to main content

​
Authentication Endpoints

The authentication endpoints provide comprehensive user management, session handling, and security features for the Shop API. All authentication flows are designed for modern mobile and web applications.
All authentication endpoints are automatically documented below from the OpenAPI specification. This overview categorizes endpoints by functionality and provides usage context.

​
Endpoint Categories

​
QR Code Authentication

Desktop-to-mobile authentication flow for seamless login:
  • POST /{locale}/shop/auth/qr-login/generate - Generate QR session
  • POST /{locale}/shop/auth/qr-login/poll/{sessionId} - Poll session status
  • POST /{locale}/shop/ably/token - Get Ably WebSocket token
Use Case: Desktop applications where users want to login using their mobile device.

​
Session Management

JWT token lifecycle and session handling:
  • POST /{locale}/shop/auth/refresh - Refresh expired access token
  • POST /{locale}/shop/auth/logout - End user session
  • GET /{locale}/shop/auth/me - Get current user information
Token Details:
  • Access tokens expire after 1 hour
  • Refresh tokens are valid for 30 days
  • Automatic token rotation on refresh

​
User Profile Management

Comprehensive user data and preferences management:
  • GET /{locale}/shop/auth/me - Get complete user profile
  • PUT /{locale}/shop/auth/profile - Update user details (name, email)
  • GET /{locale}/shop/auth/preferences - Get user preferences
  • PUT /{locale}/shop/auth/preferences - Update notification/privacy settings

​
User Statistics & Analytics

User engagement and loyalty metrics:
  • GET /{locale}/shop/auth/statistics - Get user loyalty statistics
  • Includes: total cards, points balance, coupons, achievements

​
Account Management

Advanced account operations:
  • DELETE /{locale}/shop/auth/account - Delete/deactivate user account
Account deletion is irreversible and removes all user data including loyalty cards, points, and transaction history.

​
Authentication Methods Required

Endpoint GroupAuthenticationNotes
QR GenerationAPI CredentialsPublic endpoints
Session ManagementJWT TokenUser context required
Profile ManagementJWT TokenUser context required
StatisticsJWT TokenUser context required

​
Common Use Cases

​
Desktop QR Login

Scenario: Desktop application login via mobile 
# 1. Desktop generates QR session
POST /{locale}/shop/auth/qr-login/generate

# 2. Get Ably token and subscribe to real-time events
POST /{locale}/shop/ably/token

# 3. User scans QR with Loyalty.lt mobile app

# 4. Desktop receives authentication tokens via Ably WebSocket

​
Response Examples

​
Successful Login Response

{
  "success": true,
  "message": "Login successful",
  "data": {
    "user": {
      "id": 123,
      "phone": "+37060000000", 
      "email": "user@example.com",
      "name": "Jonas Jonaitis",
      "phone_verified_at": "2024-01-15T10:30:00Z",
      "created_at": "2024-01-01T00:00:00Z"
    },
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "refresh_token": "refresh_token_string",
    "expires_in": 3600
  }
}

​
User Statistics Response

{
  "success": true,
  "data": {
    "total_cards": 5,
    "total_points": 2450,
    "total_coupons": 12,
    "active_coupons": 8,
    "completed_games": 15,
    "level": "Gold Member"
  }
}

​
Security Features

​
Rate Limiting

  • QR Login: 10 per hour per session
  • API Calls: 1000 per hour per JWT token

​
Anti-Fraud Protection

  • Device Tracking: Suspicious device detection
  • IP Monitoring: Unusual location alerts
  • Session Security: Automatic logout on suspicious activity

​
Data Protection

  • GDPR Compliant: Right to deletion and data export
  • Phone Verification: Required for all registrations
  • Secure Storage: Encrypted sensitive data
  • Audit Logging: Complete authentication activity logs

​
Error Handling

Common authentication errors and their resolutions:
Error CodeDescriptionSolution
TOKEN_EXPIREDJWT token expiredUse refresh token endpoint
QR_SESSION_EXPIREDQR login session expiredGenerate new QR session

​
Next Steps

Loyalty Cards API

Manage customer loyalty cards after authentication

Points System API

Award and redeem loyalty points for authenticated users

User Preferences

Customize user experience and notification settings

Error Handling Guide

Implement robust error handling for auth flows
Interactive Testing: All authentication endpoints can be tested directly below using the auto-generated API reference. Use the staging environment for safe testing.