Subtask 2-1: Authentication Documentation (Client-Id + Api-Key)

Task: Extract authentication documentation (Client-Id + Api-Key) Date: 2026-02-10 Status: ✅ COMPLETED

---

Executive Summary

Comprehensive authentication documentation for Ozon Seller API, including credential acquisition, header specifications, usage examples, and security best practices.

---

Authentication Headers

Required Headers

Ozon Seller API uses two HTTP headers for authentication:

Header Name	Type	Description	Example
Client-Id	String	Seller account client identifier	123456789
Api-Key	String	API key for authentication	your-api-key-here

Header Format

All API requests must include these headers:

POST /v1/product/list HTTP/1.1
Host: api-seller.ozon.ru
Client-Id: 123456789
Api-Key: your-api-key-here
Content-Type: application/json

---

Base URL

https://api-seller.ozon.ru

All API endpoints are accessed via this base URL.

---

How to Obtain Credentials

Step-by-Step Guide

1. Login to Seller Cabinet

• Navigate to seller.ozon.ru
• Log in with an account that has administrator rights
• Ensure your account has permission to manage API keys

2. Navigate to API Settings

• Click your avatar/icon in the top right corner of the interface
• Select "Настройки" (Settings) from the dropdown menu
• Go to "API ключи" (API Keys) or "Seller API" section

3. Obtain Client-Id

• Client-Id is auto-generated and already displayed on the API keys interface
• Simply copy the Client-Id value
• No manual generation required

4. Generate Api-Key

• Click the "Сгенерировать ключ" (Generate key) button
• Enter a descriptive name for the key (e.g., "Production System", "Integration App")
• Select the role/access level for the key:
  • Администратор (Administrator) - Full access to all API methods
  • Other permission levels with restricted access
• Click "Подтвердить" (Confirm) to generate
• ⚠️ CRITICAL: The Api-Key is displayed only once after generation
• Copy and save it immediately in a secure location

Visual Navigation Path

seller.ozon.ru
    ↓
[Top Right Avatar Icon]
    ↓
Настройки (Settings)
    ↓
API ключи (API Keys)
    ↓
┌─────────────────────────────────┐
│ Client-Id: [Auto-generated]     │ ← Copy this
└─────────────────────────────────┘
    ↓
[Сгенерировать ключ] (Generate Key)
    ↓
┌─────────────────────────────────┐
│ 1. Enter Key Name               │
│ 2. Select Role (Administrator)  │
│ 3. Confirm                      │
└─────────────────────────────────┘
    ↓
┌─────────────────────────────────┐
│ Api-Key: [Shown only once]      │ ← Copy this NOW!
└─────────────────────────────────┘

---

API Key Management

Multiple Keys

• You can create multiple API keys for different integration systems
• Recommended practice: Use separate keys for:
  • Production environment
  • Development/testing environment
  • Different third-party integrations

Key Security

• ⚠️ Api-Key is displayed only once after generation
• Store keys securely (use environment variables, secret management systems)
• Never commit keys to version control (Git, etc.)
• Rotate keys periodically for security
• Delete unused keys immediately

Role-Based Access Control

When creating an API key, you can specify the access level:

• Administrator: Full access to all Seller API methods
• Restricted roles: Limited access to specific API categories

Reference: Role Mapping Documentation

---

Usage Examples

Python (Async)

from ozon_api import OzonAPI
import asyncio

async def main():
    # Recommended: using context manager
    async with OzonAPI(
        client_id="your_client_id",
        api_key="your_api_key"
    ) as api:
        # Get product list
        products = await api.product_list(...)
        print(products)

if __name__ == "__main__":
    asyncio.run(main())

Python (HTTP Client)

import requests

headers = {
    "Client-Id": "your_client_id",
    "Api-Key": "your_api_key",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://api-seller.ozon.ru/v1/product/list",
    headers=headers,
    json={"page": 1, "page_size": 100}
)

TypeScript/JavaScript

import { OzonSellerAPI } from 'daytona-ozon-seller-api';

const api = new OzonSellerAPI({
  clientId: 'your-client-id',
  apiKey: 'your-api-key'
});

// Get products
const products = await api.product.getList({ limit: 10 });

// Get FBS orders
const orders = await api.fbs.getOrdersList({
  filter: { status: 'awaiting_packaging' }
});

JavaScript (Fetch)

const headers = {
  "Client-Id": "your_client_id",
  "Api-Key": "your_api_key",
  "Content-Type": "application/json"
};

fetch("https://api-seller.ozon.ru/v1/product/list", {
  method: "POST",
  headers: headers,
  body: JSON.stringify({ page: 1, page_size: 100 })
})
.then(response => response.json())
.then(data => console.log(data));

cURL

curl -X POST "https://api-seller.ozon.ru/v1/product/list" \
  -H "Client-Id: your_client_id" \
  -H "Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "page_size": 100
  }'

PHP

use Gam6itko\OzonSeller\Service\V1\ProductService;

$client = new GuzzleHttp\Client([
    'base_uri' => 'https://api-seller.ozon.ru',
    'headers' => [
        'Client-Id' => 'your_client_id',
        'Api-Key' => 'your_api_key',
        'Content-Type' => 'application/json'
    ]
]);

$productService = new ProductService($client);
$products = $productService->list(['page' => 1, 'page_size' => 100]);

Go

package main

import (
    "context"
    "github.com/diphantxm/ozon-api-client"
)

func main() {
    client := ozon_api.NewClient(
        "your_client_id",
        "your_api_key",
    )

    products, err := client.Product().List(context.Background(), ...)
    if err != nil {
        panic(err)
    }
}

---

Authentication Best Practices

Security

1. Never expose credentials in client-side code (browser, mobile apps)
2. Use environment variables for storing credentials
3. Implement proper secret management in production:
   • AWS Secrets Manager
   • Azure Key Vault
   • HashiCorp Vault
4. Rotate keys regularly (recommended: every 90 days)
5. Use separate keys for different environments

Error Handling

Authentication errors:

HTTP Code	Error Type	Description
400	OzonAPIClientError	Invalid request format
403	OzonAPIForbiddenError	Invalid credentials or insufficient permissions
404	OzonAPINotFoundError	Endpoint not found
409	OzonAPIConflictError	Request conflict
500	OzonAPIServerError	Server error

Example error response:

{
  "code": 403,
  "message": "Invalid Client-Id or Api-Key",
  "details": "Authentication failed"
}

Configuration Example

Environment Variables (.env):

OZON_CLIENT_ID=your_client_id
OZON_API_KEY=your_api_key
OZON_API_URL=https://api-seller.ozon.ru

Python with python-dotenv:

from dotenv import load_dotenv
import os

load_dotenv()

client_id = os.getenv("OZON_CLIENT_ID")
api_key = os.getenv("OZON_API_KEY")

---

Language Support

The API supports multiple languages via the Accept-Language header or client configuration:

Supported Languages:

• DEFAULT - Default language
• RU - Russian
• EN - English
• TR - Turkish
• ZH_HANS - Chinese (Simplified)

Python Example:

api = OzonAPI(client_id="...", api_key="...")
api.language = "RU"  # Set language

---

Troubleshooting

Common Issues

1. "Invalid Client-Id or Api-Key"

• Verify both credentials are correct
• Ensure no extra spaces in header values
• Check that the API key hasn't been deleted or revoked

2. "Access Denied" (403)

• Verify the key's role has permission for the requested endpoint
• Check role mappings: Role Documentation

3. "Rate Limit Exceeded" (429)

• Implement request throttling
• Add retry logic with exponential backoff
• Check rate limit documentation

4. "Key Not Found"

• Api-Key is case-sensitive
• Ensure you copied the entire key
• Regenerate key if lost (cannot be recovered)

---

Additional Resources

Official Documentation

• Ozon API Documentation
• Getting Started Guide
• How to Generate API Key
• Role Mapping Reference

Community Resources

• Ozon for Dev
• Telegram (Russian)
• Telegram (English)

Client Libraries

• Python: ozon-api (Async, v1.5.0)
• TypeScript: ozon-daytona-seller-api
• PHP: gam6itko/ozon-seller
• Go: diPhantxm/ozon-api-client

---

Summary

Key Points:

• ✅ Headers: Client-Id and Api-Key
• ✅ Base URL: https://api-seller.ozon.ru
• ✅ Client-Id: Auto-generated, visible in settings
• ✅ Api-Key: Generated once, displayed only once
• ✅ Location: Settings → API Keys
• ✅ Security: Use environment variables, never commit to Git
• ✅ Multiple keys: Create separate keys for different systems
• ✅ Role-based access: Administrator or restricted roles

---

Authentication documentation complete and verified. Ready for integration into final 01_OZON_API_RUS.md document.