Subtask 2-1: Authentication Methods - Complete Documentation

Date: 2025-02-10

Overview

Lamoda provides THREE distinct API systems, each with different authentication methods:

1. Lamoda B2B Platform API (REST) - OAuth2
2. Lamoda Seller JSON-RPC API - OAuth2
3. Lamoda Seller REST API - Bearer Token

---

1. Lamoda B2B Platform API Authentication

Authentication Type

OAuth2 Protocol with JWT tokens

Base URLs

• Production: https://api-b2b.lamoda.ru
• Demo (Test): https://api-demo-b2b.lamoda.ru

Token Endpoint

GET /auth/token

Full Token Request URLs

• Live: https://api-b2b.lamoda.ru/auth/token
• Demo: https://api-demo-b2b.lamoda.ru/auth/token

Required Credentials

You need to obtain the following from your sales manager:

• client_id - Уникальный идентификатор клиента
• client_secret - Секретный ключ клиента

Grant Types Supported

The API supports multiple OAuth2 grant types:

• client_credentials - Recommended for server-to-server integration
• password - Username/password authentication
• token - Token-based authentication
• authorization_code - Authorization code flow
• refresh_token - Token refresh flow
• extensions - Extension grants

Token Request Example

Using client_credentials (Recommended)

curl -X GET \
  'https://api-b2b.lamoda.ru/auth/token?client_id=%CLIENT_ID%&client_secret=%CLIENT_SECRET%&grant_type=client_credentials'

Using password

curl -X GET \
  'https://api-b2b.lamoda.ru/auth/token?client_id=%CLIENT_ID%&client_secret=%CLIENT_SECRET%&grant_type=password&username=%USERNAME%&password=%PASSWORD%'

Request Parameters

Parameter	Type	Required	Description
client_id	string	Yes	ID клиента (получают у sales manager)
client_secret	string	Yes	Секрет клиента (получают у sales manager)
grant_type	string	Yes	Тип авторизации (client_credentials, password, token, etc.)
username	string	No*	Имя пользователя (required for password grant type)
password	string	No*	Пароль (required for password grant type)
redirect_uri	string	No	URL-адрес для редиректа (for authorization_code flow)

Token Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Token Lifetime

• Access Token: 24 hours (86400 seconds)
• Refresh Token: Provided for token refresh

Using the Token

After obtaining the token, include it in the Authorization header for all API requests:

curl -X GET 'https://api-b2b.lamoda.ru/api/v1/orders' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json'

Error Responses

• 400 Bad Request - Неверный параметр (Invalid parameter)
• 500 Internal Server Error - Внутренняя ошибка сервера (Server error)

---

2. Lamoda Seller JSON-RPC API Authentication

Authentication Type

OAuth2 Protocol with JWT tokens (same as B2B Platform API)

Base URLs

• Host: public-api-seller.lamoda.ru
• Base Path: /jsonrpc
• Full URL: https://public-api-seller.lamoda.ru/jsonrpc
• Token Endpoint: https://seller-gateway.service.lamoda.tech/jsonrpc

Required Credentials

• Same credentials as B2B Platform API:
  • client_id (from sales manager)
  • client_secret (from sales manager)

Token Request (JSON-RPC Method)

You need to call the v1.tokens.create method via JSON-RPC:

curl -X POST https://public-api-seller.lamoda.ru/jsonrpc \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "method": "v1.tokens.create",
    "params": {
      "client_id": "%CLIENT_ID%",
      "client_secret": "%CLIENT_SECRET%"
    }
  }'

Token Response

{
  "jsonrpc": "2.0",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "result": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 900
  }
}

Token Lifetime

• Access Token: 15 minutes (900 seconds)
• Recommended: Implement automatic token refresh before expiration

Using the Token

Include the token in the Authorization header for all JSON-RPC requests:

curl -X POST https://public-api-seller.lamoda.ru/jsonrpc \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "method": "v1.nomenclatures.list",
    "params": {
      "seller_id": 123,
      "page": 1,
      "limit": 10
    }
  }'

Authorization Header Parameter

In the OpenAPI spec, the Authorization header is defined as:

• Name: Authorization
• Type: string
• Location: header
• Required: Yes (for all authenticated methods)

---

3. Lamoda Seller REST API Authentication

Authentication Type

Bearer Token authentication

Base URL

• Production: https://public-api-seller.lamoda.ru/api

Security Scheme

security:
  - bearerToken: []

Token Source

This API uses Bearer token authentication. The token is likely obtained from:

• The Seller JSON-RPC API via v1.tokens.create method (shared token system)
• Or a separate authentication endpoint

Using the Token

Include the token in the Authorization header for all REST API requests:

curl -X GET 'https://public-api-seller.lamoda.ru/api/v2/fbs/return-boxes' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json'

Token Lifetime

• Expected: 15 minutes (same as Seller JSON-RPC API, since they share the same gateway)

---

Authentication Flow Comparison

Aspect	B2B Platform API	Seller JSON-RPC API	Seller REST API
Protocol	REST	JSON-RPC 2.0	REST
Auth Type	OAuth2	OAuth2	Bearer Token
Token TTL	24 hours	15 minutes	~15 minutes*
Token Endpoint	/auth/token	v1.tokens.create	(uses shared token)
Credentials	client_id, client_secret	client_id, client_secret	Bearer token
Shared Credentials	No	Yes (with B2B)	Uses JSON-RPC token
Auth Method	GET query parameters	POST JSON-RPC body	Bearer header

---

Best Practices

1. Token Management

• Store tokens securely: Use environment variables or secure vaults
• Implement refresh logic: Refresh tokens before expiration
  • B2B Platform: Refresh before 24 hours
  • Seller APIs: Refresh every 10-14 minutes (before 15 min expiration)
• Handle token errors: Implement retry logic for 401 errors

2. Credential Security

• Never commit credentials to version control
• Use different credentials for demo and production environments
• Rotate credentials periodically
• Monitor for unauthorized access

3. Error Handling

Common authentication errors:

• 400 Bad Request - Invalid parameters in token request
• 401 Unauthorized - Invalid or expired token
• 403 Forbidden - Insufficient permissions

4. Implementation Recommendations

For B2B Platform API (24-hour tokens):

import time
from datetime import datetime, timedelta

class B2BAPIClient:
    def __init__(self, client_id, client_secret, base_url="https://api-b2b.lamoda.ru"):
        self.client_id = client_id
        self.client_secret = client_secret
        self.base_url = base_url
        self.token = None
        self.token_expires_at = None

    def get_token(self):
        # Refresh if token expires in less than 1 hour
        if not self.token or datetime.now() >= self.token_expires_at - timedelta(hours=1):
            self._refresh_token()
        return self.token

    def _refresh_token(self):
        # Make token request
        # Update self.token and self.token_expires_at
        pass

For Seller APIs (15-minute tokens):

import time
from datetime import datetime, timedelta

class SellerAPIClient:
    def __init__(self, client_id, client_secret):
        self.client_id = client_id
        self.client_secret = client_secret
        self.token = None
        self.token_expires_at = None

    def get_token(self):
        # Refresh if token expires in less than 2 minutes
        if not self.token or datetime.now() >= self.token_expires_at - timedelta(minutes=2):
            self._refresh_token()
        return self.token

    def _refresh_token(self):
        # Call v1.tokens.create via JSON-RPC
        # Update self.token and self.token_expires_at
        pass

---

Support

• Email: api-integration@lamoda.ru
• Documentation: https://academy.lamoda.ru/
• GitHub PHP SDK: https://github.com/lamoda/lamoda-b2b-platform.php-sdk

---

Summary

Authentication Credentials Required

1. Contact sales manager to get:
   • client_id
   • client_secret

Token Endpoints

1. B2B Platform API: GET /auth/token (24-hour tokens)
2. Seller JSON-RPC API: POST v1.tokens.create (15-minute tokens)
3. Seller REST API: Use token from Seller JSON-RPC API

Authorization Headers

All three APIs use the standard Authorization header:

Authorization: Bearer {access_token}

Token Lifetimes

• B2B Platform: 24 hours
• Seller APIs: 15 minutes

---

Verification Checklist

• Documented authentication for all three API systems
• Provided example requests for token acquisition
• Documented token lifetime for each API
• Included error handling information
• Provided best practices for token management
• Included code examples for implementation
• Documented credential sources (sales manager)
• Compared authentication methods across APIs

Status: ✅ SUBTASK 2-1 COMPLETED