Authentication Overview

Loyalty.lt provides multiple authentication methods depending on the API layer you’re using and your integration requirements. This guide explains each method and when to use them.

Authentication Methods

Choose the authentication method that best fits your integration needs and security requirements.

API Credentials

Best for: Shop APIs, server-to-server communication

Simple header-based authentication
API Key + Secret combination
Suitable for backend integrations

JWT Tokens

Best for: SDK APIs, user-based applications

Secure token-based authentication
User-specific permissions
Real-time features support

OAuth 2.0

Best for: Third-party integrations

Industry standard authorization
Granular permission scopes
Secure delegation of access

Webhooks

Best for: Event-driven integrations

HMAC signature verification
Secure event delivery
Real-time notifications

API Credentials Authentication

Overview

API Credentials are the simplest authentication method, using a combination of API Key and API Secret sent as HTTP headers.

Usage
Obtaining Credentials
Best Practices

Endpoints: Shop APIs (/api/*)
Method: HTTP Headers
Security: HTTPS required

X-API-Key: your_api_key_here
X-API-Secret: your_api_secret_here

Example Implementation

const apiKey = process.env.LOYALTY_API_KEY;
const apiSecret = process.env.LOYALTY_API_SECRET;

const response = await fetch('https://staging-api.loyalty.lt/api/loyalty-cards', {
  method: 'GET',
  headers: {
    'X-API-Key': apiKey,
    'X-API-Secret': apiSecret,
    'Content-Type': 'application/json'
  }
});

if (!response.ok) {
  throw new Error(`API request failed: ${response.status}`);
}

const data = await response.json();

JWT Token Authentication

Overview

JWT (JSON Web Tokens) provide secure, user-specific authentication for SDK and Partner APIs with support for permissions and real-time features.

Token Flow
Token Structure
Permissions

Initial Authentication: Use API credentials to request JWT
Token Usage: Include JWT in Authorization header
Token Refresh: Renew tokens before expiration
Logout: Invalidate tokens when done

Obtaining JWT Tokens

curl -X POST 'https://staging-api.loyalty.lt/en/sdk/auth/login' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your_api_key' \
  -H 'X-API-Secret: your_api_secret' \
  -d '{
    "email": "user@example.com",
    "password": "user_password"
  }'

{
  "success": true,
  "data": {
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "refresh_token": "def50200a1b2c3d4e5f6...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "user": {
      "id": 123,
      "email": "user@example.com",
      "permissions": ["read", "write"],
      "shop_id": 456
    }
  }
}

Using JWT Tokens

const token = localStorage.getItem('loyalty_access_token');

const response = await fetch('https://staging-api.loyalty.lt/en/sdk/loyalty-cards', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
});

// Handle token expiration
if (response.status === 401) {
  await refreshToken();
  // Retry the request with new token
}

Token Refresh

curl -X POST 'https://staging-api.loyalty.lt/en/sdk/auth/refresh' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your_refresh_token'

{
  "success": true,
  "data": {
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "refresh_token": "def50200a1b2c3d4e5f6...",
    "token_type": "Bearer",
    "expires_in": 3600
  }
}

OAuth 2.0 Authentication

Overview

OAuth 2.0 provides secure, standardized authorization for third-party applications that need to access Loyalty.lt APIs on behalf of users.

Grant Types
Scopes
Registration

Authorization Code: For web applications with server-side code
Client Credentials: For server-to-server communication
Implicit: For single-page applications (deprecated)

Authorization Code Flow

Authorization Request

Redirect user to authorization server:

https://staging-api.loyalty.lt/oauth/authorize?
  response_type=code&
  client_id=your_client_id&
  redirect_uri=https://your-app.com/callback&
  scope=loyalty:read+points:manage&
  state=random_state_string

User Authorization

User grants permission and is redirected back:

https://your-app.com/callback?
  code=authorization_code&
  state=random_state_string

Token Exchange

Exchange authorization code for access token:

curl -X POST 'https://staging-api.loyalty.lt/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code&
      code=authorization_code&
      redirect_uri=https://your-app.com/callback&
      client_id=your_client_id&
      client_secret=your_client_secret'

API Access

Use access token to make API requests:

curl -X GET 'https://staging-api.loyalty.lt/en/sdk/loyalty-cards' \
  -H 'Authorization: Bearer access_token'

Webhook Authentication

Overview

Webhooks use HMAC-SHA256 signatures to verify that events are sent from Loyalty.lt and haven’t been tampered with.

Signature Verification
Setup
Event Types

Each webhook includes a signature header:

X-Loyalty-Signature: sha256=abcdef123456789...

Verify using your webhook secret:

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  
  return `sha256=${expected}` === signature;
}

Webhook Implementation

const express = require('express');
const crypto = require('crypto');
const app = express();

// Use raw body parser for signature verification
app.use('/webhooks', express.raw({ type: 'application/json' }));

app.post('/webhooks/loyalty', (req, res) => {
  const signature = req.get('X-Loyalty-Signature');
  const payload = req.body;
  
  if (!verifySignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  const event = JSON.parse(payload);
  
  switch (event.type) {
    case 'points.awarded':
      handlePointsAwarded(event.data);
      break;
    case 'loyalty_card.created':
      handleCardCreated(event.data);
      break;
    default:
      console.log('Unhandled event type:', event.type);
  }
  
  res.status(200).send('OK');
});

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  
  return `sha256=${expected}` === signature;
}

Error Handling

Authentication Errors

401 Unauthorized

Cause: Invalid or missing credentials/token
Solution: Check credentials or refresh JWT token

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API credentials"
  }
}

403 Forbidden

Cause: Valid credentials but insufficient permissions
Solution: Check required permissions for endpoint

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions for this action",
    "required_permissions": ["points:manage"]
  }
}

429 Rate Limited

Cause: Too many requests in time window
Solution: Implement exponential backoff

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded",
    "retry_after": 60
  }
}

Best Practices

Token Management

Implement automatic token refresh
Store tokens securely
Handle token expiration gracefully
Log authentication events

Error Handling

Implement retry logic with backoff
Handle network timeouts
Log authentication failures
Provide user-friendly error messages

Security

Use HTTPS for all requests
Validate webhook signatures
Rotate credentials regularly
Monitor for suspicious activity

Performance

Cache tokens until expiration
Use connection pooling
Implement rate limiting
Monitor API usage

Testing Authentication

Development Environment

Use staging environment for testing:

# Test API credentials
curl -X GET 'https://staging-api.loyalty.lt/api/health' \
  -H 'X-API-Key: your_staging_key' \
  -H 'X-API-Secret: your_staging_secret'

# Test JWT authentication
curl -X POST 'https://staging-api.loyalty.lt/en/sdk/auth/login' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your_staging_key' \
  -H 'X-API-Secret: your_staging_secret' \
  -d '{"email": "test@example.com", "password": "password"}'

Webhook Testing

Use tools like ngrok for local webhook development:

# Install ngrok
npm install -g ngrok

# Expose local server
ngrok http 3000

# Use ngrok URL in webhook configuration
# https://abc123.ngrok.io/webhooks/loyalty

Next Steps

JWT Tokens

Learn more about JWT token implementation and management.

API Credentials

Detailed guide on managing API credentials securely.

Shop APIs

Start using Shop APIs with your credentials.

SDK APIs

Implement SDK authentication in your application.

Introduction

Authentication

Loyalty Cards

Points & Transactions

Offers & Coupons

Partner APIs

​Authentication Overview

​Authentication Methods

API Credentials

JWT Tokens

OAuth 2.0

Webhooks

​API Credentials Authentication

​Overview

​Example Implementation

​JWT Token Authentication

​Overview

​Obtaining JWT Tokens

​Using JWT Tokens

​Token Refresh

​OAuth 2.0 Authentication

​Overview

​Authorization Code Flow

​Webhook Authentication

​Overview

​Webhook Implementation

​Error Handling

​Authentication Errors

​Best Practices

Token Management

Error Handling

Security

Performance

​Testing Authentication

​Development Environment

​Webhook Testing

​Next Steps

JWT Tokens

API Credentials

Shop APIs

SDK APIs

Authentication Overview

Authentication Methods

API Credentials Authentication

Overview

Example Implementation

JWT Token Authentication

Overview

Obtaining JWT Tokens

Using JWT Tokens

Token Refresh

OAuth 2.0 Authentication

Overview

Authorization Code Flow

Webhook Authentication

Overview

Webhook Implementation

Error Handling

Authentication Errors

Best Practices

Testing Authentication

Development Environment

Webhook Testing

Next Steps