API Authentication

The Loyalty.lt API supports multiple authentication methods designed for different integration scenarios. Choose the method that best fits your application’s architecture and security requirements.

All authentication methods use HTTPS encryption and include rate limiting for security. All examples below use real endpoints that you can test.

Authentication Methods Overview

QR Code Authentication is the primary login method for Loyalty.lt, enabling secure cross-device authentication with real-time communication.

Method	Use Case	Security Level	Rate Limit
🔥 QR Code Auth	Primary: Desktop/Mobile	High	1,000/hour
Phone + OTP	Mobile app login	High	500/hour
API Credentials	Server integrations	High	2,000/hour
JWT Tokens	User sessions	Medium	1,000/hour
Partner Authentication	Partner management	High	5,000/hour

QR Code Authentication (Primary Method)

Best for: Desktop/web applications with mobile app authentication, cross-device login QR Code authentication is the primary authentication method for Loyalty.lt, providing secure login by scanning QR codes with the mobile app. This method offers enhanced security through device separation and real-time verification.

How QR Authentication Works

Generate QR Session

Desktop/web app creates a unique QR code session with 5-minute expiration.

Display QR Code

QR code is displayed to the user on desktop/web interface.

Mobile Scan

Authenticated mobile user scans the QR code using the Loyalty.lt app.

User Confirmation

User confirms login on mobile device after reviewing session details.

Real-time Authentication

Desktop/web receives authentication tokens via Ably WebSocket connection.

Quick Start Example

// 1. Generate QR session
const qrResponse = await fetch('/en/shop/auth/qr-login/generate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ device_name: 'Web Browser' })
});

const { session_id, qr_code } = qrResponse.data;

// 2. Subscribe to real-time updates
const ably = new Ably.Realtime('YOUR_ABLY_KEY');
const channel = ably.channels.get(`qr-login:${session_id}`);

channel.subscribe('qr_login_status', (message) => {
  if (message.data.status === 'confirmed') {
    // User authenticated - redirect to dashboard
    localStorage.setItem('auth_token', message.data.token);
    window.location.href = '/dashboard';
  }
});

// 3. Display QR code for user to scan
displayQRCode(qr_code);

Security Features

Session Expiration: 5-minute timeout for enhanced security
Device Separation: Authentication happens on separate trusted device
Real-time Verification: Instant status updates via WebSocket
User Authorization: Only authenticated mobile users can complete login

For complete QR authentication documentation with all endpoints, examples, and implementation guides, see the QR Code Authentication section.

Phone + OTP Authentication

Best for: Mobile applications, direct phone number verification Alternative authentication method using phone number and one-time password (OTP) verification.

Basic Flow

Request OTP

Send OTP code to user’s phone number for authentication.

User Enters OTP

User receives and enters the 6-digit verification code.

Verify & Login

API verifies OTP and returns JWT tokens for session management.

Quick Example

// 1. Request OTP
await fetch('/en/shop/auth/request-otp', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    phone: '+37060000000',
    type: 'login'
  })
});

// 2. Login with OTP
const loginResponse = await fetch('/en/shop/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    phone: '+37060000000',
    otp: '123456',
    device_name: 'Mobile App'
  })
});

const { token, refresh_token } = loginResponse.data;

API Credentials

Best for: E-commerce platforms, POS systems, server-to-server integrations API Credentials provide the highest level of security and are designed for backend integrations where you can safely store secrets.

How API Credentials Work

Generate credentials in the Partner Dashboard
Store securely on your server (never in frontend code)
Include headers in every API request
Automatic validation by our API gateway

Getting API Credentials

Access Partner Dashboard

Visit partners.loyalty.lt and sign in to your account.

Navigate to API Settings

Go to Settings → API Credentials in your dashboard.

Generate New Credentials

Click Generate New API Key and securely store both the API Key and API Secret.

Using API Credentials

Include these headers in every request:

curl -X GET "https://staging-api.loyalty.lt/en/shop/loyalty-cards" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Secret: your_api_secret_here" \
  -H "Content-Type: application/json"

Required Headers:

X-API-Key: Your public API key
X-API-Secret: Your private API secret
Content-Type: Always application/json

Security Features

Restrict API access to specific IP addresses for enhanced security.

{
  "allowed_ips": [
    "203.0.113.0/24",
    "198.51.100.42"
  ]
}

JWT Tokens

Best for: Mobile apps, customer portals, user-specific operations JWT tokens provide session-based authentication for customer-facing features where users log in with their phone number and OTP.

Phone + OTP Authentication Flow

The primary method for customer authentication:

Request OTP

Send OTP code to customer’s phone:

curl -X POST "https://staging-api.loyalty.lt/en/shop/auth/request-otp" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+37060000000",
    "type": "login"
  }'

Verify OTP & Login

Verify the OTP code and receive JWT token:

curl -X POST "https://staging-api.loyalty.lt/en/shop/auth/login" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+37060000000",
    "otp": "123456"
  }'

Response:

{
  "success": true,
  "message": "Login successful",
  "data": {
    "user": {
      "id": 123,
      "phone": "+37060000000",
      "name": "Jonas Jonaitis"
    },
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "refresh_token": "refresh_token_here",
    "expires_in": 3600
  }
}

Use JWT Token

Include the JWT token in subsequent requests:

curl -X GET "https://staging-api.loyalty.lt/en/shop/auth/me" \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." \
  -H "Content-Type: application/json"

QR Code Authentication

Alternative authentication method for desktop-to-mobile scenarios:

Generate QR Session

curl -X POST "https://staging-api.loyalty.lt/en/shop/auth/qr-login/generate" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{"device_name": "Desktop Browser"}'

Display QR Code

Show the QR code to the user and poll for status:

curl -X GET "https://staging-api.loyalty.lt/en/shop/auth/qr-login/poll/session_id"

Mobile Scan & Confirm

User scans QR with mobile app and confirms login.

Token Management

Token Lifecycle:

Access Token: 1 hour lifetime
Refresh Token: 30 days lifetime
Auto-refresh: Seamless token renewal

Refresh Expired Tokens:

curl -X POST "https://staging-api.loyalty.lt/en/shop/auth/refresh" \
  -H "Authorization: Bearer expired_token" \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "your_refresh_token"}'

Logout:

curl -X POST "https://staging-api.loyalty.lt/en/shop/auth/logout" \
  -H "Authorization: Bearer your_token"

Authentication Comparison

Feature	API Credentials	JWT Tokens
Use Case	Server backends	User sessions
Storage	Server environment	Client app
Expires	Never (unless revoked)	1 hour (renewable)
Rate Limit	2,000/hour	1,000/hour
User Context	No	Yes (specific user)
Security	Very High	Medium

Environment-Specific Examples

Use for development and testing:

# Base URL
BASE_URL="https://staging-api.loyalty.lt"

# API Credentials test
curl -X GET "$BASE_URL/en/shop/loyalty-cards" \
  -H "X-API-Key: test_api_key" \
  -H "X-API-Secret: test_api_secret"

# JWT test
curl -X GET "$BASE_URL/en/shop/auth/me" \
  -H "Authorization: Bearer test_jwt_token"

Safe to test with any data - no impact on production.

Common Authentication Errors

Error Code	Status	Cause	Solution
`AUTH_REQUIRED`	401	Missing auth headers	Add X-API-Key and X-API-Secret
`INVALID_CREDENTIALS`	401	Wrong API credentials	Verify key/secret in dashboard
`TOKEN_EXPIRED`	401	JWT token expired	Use refresh token endpoint
`INSUFFICIENT_PERMISSIONS`	403	Limited access rights	Check partner permissions
`RATE_LIMIT_EXCEEDED`	429	Too many requests	Implement exponential backoff

Best Practices

Never expose credentials in frontend code or logs
Use environment variables for credential storage
Implement token refresh logic for JWT tokens
Validate responses and handle errors gracefully
Use HTTPS only for all API communications

Testing Authentication

Quick Test Endpoints

Test your authentication setup with these endpoints: API Credentials Test:

curl -X GET "https://staging-api.loyalty.lt/shop/health" \
  -H "X-API-Key: your_key" \
  -H "X-API-Secret: your_secret"

JWT Token Test:

curl -X GET "https://staging-api.loyalty.lt/en/shop/auth/me" \
  -H "Authorization: Bearer your_jwt_token"

Postman Collection

Download our Postman collection for easy API testing:

Download Postman Collection

Pre-configured requests with authentication examples

Support

Test Endpoints

Interactive testing for all auth endpoints

Partner Dashboard

Manage credentials and view usage analytics

Authentication is handled automatically when using our official SDKs. The manual examples above are provided for custom integrations and debugging.

Introduction

Authentication

Loyalty Cards

Points & Transactions

Offers & Coupons

Partner APIs

Authentication

API Authentication

Authentication Methods Overview

QR Code Authentication (Primary Method)

How QR Authentication Works

Quick Start Example

Security Features

Phone + OTP Authentication

Basic Flow

Quick Example

API Credentials

How API Credentials Work

Getting API Credentials

Using API Credentials

Security Features

JWT Tokens

Phone + OTP Authentication Flow

QR Code Authentication

Token Management

Authentication Comparison

Environment-Specific Examples

Common Authentication Errors

Best Practices

Testing Authentication

Quick Test Endpoints

Postman Collection

Download Postman Collection

Support

Test Endpoints

Partner Dashboard

Introduction

Authentication

Loyalty Cards

Points & Transactions

Offers & Coupons

Partner APIs

​API Authentication

​Authentication Methods Overview

​QR Code Authentication (Primary Method)

​How QR Authentication Works

​Quick Start Example

​Security Features

​Phone + OTP Authentication

​Basic Flow

​Quick Example

​API Credentials

​How API Credentials Work

​Getting API Credentials

​Using API Credentials

​Security Features

​JWT Tokens

​Phone + OTP Authentication Flow

​QR Code Authentication

​Token Management

​Authentication Comparison

​Environment-Specific Examples

​Common Authentication Errors

​Best Practices

​Testing Authentication

​Quick Test Endpoints

​Postman Collection

Download Postman Collection

​Support

Test Endpoints

Partner Dashboard

API Authentication

Authentication Methods Overview

QR Code Authentication (Primary Method)

How QR Authentication Works

Quick Start Example

Security Features

Phone + OTP Authentication

Basic Flow

Quick Example

API Credentials

How API Credentials Work

Getting API Credentials

Using API Credentials

Security Features

JWT Tokens

Phone + OTP Authentication Flow

QR Code Authentication

Token Management

Authentication Comparison

Environment-Specific Examples

Common Authentication Errors

Best Practices

Testing Authentication

Quick Test Endpoints

Postman Collection

Support