Автентифікація

Усі запити до API Felo API Platform потребують автентифікації за допомогою API-ключа. Цей посібник пояснює, як автентифікувати запити та вирішувати типові проблеми з автентифікацією.

Автентифікація за API-ключем

Felo використовує автентифікацію за API-ключем для всіх endpoint v2. Ваш API-ключ ідентифікує ваш застосунок і надає доступ до можливостей платформи.

Як це працює

1. Ви отримуєте API-ключ на сторінці API-ключів Felo API Platform
2. Ви додаєте API-ключ у заголовок Authorization кожного запиту API
3. Платформа перевіряє ваш API-ключ і обробляє запит

Формат заголовка

Додайте API-ключ у заголовок Authorization, використовуючи схему автентифікації Bearer:

Authorization: Bearer YOUR_API_KEY

Приклад запиту

curl -X POST https://openapi.felo.ai/v2/chat \
  -H "Authorization: Bearer sk_live_abc123xyz789" \
  -H "Content-Type: application/json" \
  -d '{"query": "What is machine learning?"}'

Отримання API-ключа

Щоб отримати API-ключ:

1. Відкрийте сторінку API-ключів Felo API Platform
2. Увійдіть у свій обліковий запис Felo, якщо з'явиться запит
3. Введіть назву ключа та натисніть Create Key
4. Скопіюйте повний ключ, коли він з'явиться. Він показується лише один раз
5. Зберігайте ключ у безпечному місці та використовуйте його як FELO_API_KEY

Рекомендації з безпеки

1. Зберігайте API-ключі в безпечному місці

Не вшивайте API-ключі жорстко у вихідний код:

# ❌ Bad - API Key exposed in code
api_key = "sk_live_abc123xyz789"

Так — використовуйте змінні середовища або безпечну конфігурацію:

# ✅ Good - API Key from environment
import os
api_key = os.environ.get('FELO_API_KEY')

2. Використовуйте змінні середовища

Зберігайте API-ключ у змінних середовища:

Linux/macOS:

export FELO_API_KEY="sk_live_abc123xyz789"

Windows (Command Prompt):

set FELO_API_KEY=sk_live_abc123xyz789

Windows (PowerShell):

$env:FELO_API_KEY="sk_live_abc123xyz789"

3. Регулярно змінюйте ключі

Періодично генеруйте нові API-ключі та відкликайте старі, щоб мінімізувати ризики для безпеки.

4. Використовуйте різні ключі для різних середовищ

Створюйте окремі API-ключі для середовищ розробки, тестування та продакшену.

5. Ніколи не розкривайте ключі в клієнтському коді

API-ключі слід використовувати лише в серверному коді. Ніколи не додавайте їх до:

• Фронтенд-коду JavaScript
• Вихідного коду мобільних застосунків
• Публічних репозиторіїв
• Клієнтських файлів конфігурації

Помилки автентифікації

Повну структуру помилок, заголовки обмежень швидкості та політику повторних спроб див. у Помилки, обмеження та повторні спроби.

Типові коди помилок

Відхилений запит повертає стан ключа в message:

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "API Key is required",
  "request_id": "..."
}

status — це код стану HTTP. Відкликаний ключ повідомляє API Key has been revoked (keyPrefix=...). Орієнтуйтеся на код стану HTTP і code, а не на точне формулювання message.

Усунення несправностей

Якщо автентифікація не працює:

1. Перевірте, що заголовок має вигляд саме Authorization: Bearer YOUR_API_KEY.
2. Переконайтеся, що ключ не відкликано на сторінці API-ключів.
3. Переконайтеся, що середовище використовує той ключ, який ви очікуєте.
4. Згенеруйте новий ключ, якщо старий було видалено або змінено. Повний ключ показується лише один раз, під час створення.

Оглядовий контрольний список, який охоплює автентифікацію та решту платформи, див. у Усунення несправностей.

Приклад: налагодження автентифікації

import requests

url = "https://openapi.felo.ai/v2/chat"
api_key = "YOUR_API_KEY"

# Correct format
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

response = requests.post(url, headers=headers, json={"query": "test"})

if response.status_code == 401:
    error = response.json()
    print(f"Authentication failed: {error['code']}")
    print(f"Message: {error['message']}")
    print(f"Request ID: {error['request_id']}")
else:
    print("Authentication successful!")

Обмеження швидкості

Обмеження швидкості застосовуються для кожного endpoint окремо, а не глобально для API-ключа. Наразі їх застосовує лише `/v2/chat`; користувачі з чинною платною підпискою Felo звільнені від них. Інші endpoint /v2/** не мають примусових обмежень швидкості.

Відповідь 429 містить заголовки X-RateLimit-* і Retry-After. Завжди читайте чинні обмеження із заголовків відповіді, а не з документації.

Повні виміри обмежень швидкості, заголовки та політику повторних спроб див. у Помилки, обмеження та повторні спроби.

Потрібна допомога?

Якщо у вас виникають проблеми з автентифікацією:

1. Уважно перечитайте цей посібник
2. Перегляньте посібник Початок роботи
3. Перевірте свій API-ключ на сторінці API-ключів
4. Зверніться до підтримки за адресою [email protected], вказавши свій request ID

Наступні кроки

• Посібник із початку роботи — дізнайтеся, як виконати перший виклик API
• Довідник Chat API — ознайомтеся з документацією Chat API