Аутентификация и ключи API

Discuse API аутентифицирует каждый запрос с помощью ключа API. Передавайте его в заголовке запроса X-API-Key (или в поле api_key в JSON-теле). Ключи начинаются с префикса disc_, привязаны к одному проекту и полностью показываются только один раз — при создании. В этом руководстве объясняется, как их получить, использовать, защищать и ротировать.

Как работает аутентификация в Discuse?

Каждый вызов API должен содержать действительный ключ API. Discuse использует его, чтобы:

Учитывать использование в рамках квоты вашего проекта
Применять ограничение частоты запросов для каждого ключа, чтобы предотвращать злоупотребления
Привязывать запросы к нужному проекту и его настройкам
Управлять доступом к ресурсам вашего аккаунта

Получение ключа API

Шаг 1: Создайте аккаунт

Если вы еще этого не сделали, зарегистрируйте аккаунт Discuse на discuse.com. Можно начать с бесплатного тарифа Basic: он включает ежемесячный лимит запросов API, а также доступ к проверкам текста, спама, языка и изображений. Актуальные лимиты по тарифам смотрите на странице с ценами.

Шаг 2: Откройте панель управления

После входа перейдите в панель управления. Найдите раздел "API Keys" или "Developer" в навигационном меню.

Шаг 3: Сгенерируйте новый ключ

Нажмите "Create New API Key" и при желании укажите имя или описание ключа. Это поможет понять назначение каждого ключа, если вы создадите несколько.

Новый ключ API будет показан только один раз. Сразу скопируйте его и сохраните в надежном месте — позже вы не сможете снова увидеть ключ целиком.

Использование ключа API

Добавляйте ключ API в заголовок X-API-Key каждого запроса:

curl -X POST https://api.discuse.com/api/v2/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: disc_aB3dEf6GhIjKlMnOpQrStUvWxYz012345" \
  -d '{
    "content": {
      "text": "Content to analyze"
    }
  }'

Также можно передавать ключ в поле api_key внутри JSON-тела вместо заголовка, но предпочтительнее использовать заголовок, чтобы ключ не попадал в логи тела запросов.

Пример на JavaScript

const response = await fetch('https://api.discuse.com/api/v2/check', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.DISCUSE_API_KEY
  },
  body: JSON.stringify({
    content: { text: 'Content to analyze' }
  })
});

Пример на Python

import requests
import os

response = requests.post(
    'https://api.discuse.com/api/v2/check',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': os.environ['DISCUSE_API_KEY']
    },
    json={
        'content': {'text': 'Content to analyze'}
    }
)

Рекомендации по безопасности ключей API

Никогда не раскрывайте ключи в клиентском коде

Ключи API никогда не должны включаться в JavaScript, который выполняется в браузере. Клиентский код виден любому, кто откроет исходный код вашей страницы.

// WRONG - Don't do this!
const API_KEY = 'disc_aB3dEf6...'; // Exposed in browser

// CORRECT - Use a backend proxy
const response = await fetch('/api/moderate', {
  method: 'POST',
  body: JSON.stringify({ text: userInput })
});

Используйте переменные окружения

Храните ключи API в переменных окружения, а не в кодовой базе:

# .env file (add to .gitignore!)
DISCUSE_API_KEY=disc_aB3dEf6GhIjKlMnOpQrStUvWxYz012345

// Access in Node.js
const apiKey = process.env.DISCUSE_API_KEY;

Регулярно ротируйте ключи

Периодически ротируйте ключи API, особенно если подозреваете, что они могли быть скомпрометированы:

Сгенерируйте новый ключ API
Обновите приложение, чтобы оно использовало новый ключ
Убедитесь, что все работает корректно
Отзовите старый ключ

Примечание: отозванный ключ может оставаться рабочим примерно до 5 минут, потому что проверенные ключи кэшируются. Планируйте ротацию с учетом этого короткого периода перекрытия, а не рассчитывайте на мгновенное переключение.

Используйте отдельные ключи для разных сред

Создавайте разные ключи API для разработки, staging-среды и production:

Среда	Назначение ключа
Разработка	Тестирование и локальная разработка
Staging	Предпродакшен-тестирование
Production	Трафик работающего приложения

Так вы сможете отозвать скомпрометированный ключ, не затрагивая другие среды.

Как работает ограничение частоты запросов?

Ограничение частоты запросов применяется к каждому ключу API, а не к тарифу. Для каждого ключа при создании задается лимит запросов в минуту (RPM); если не указать значение, по умолчанию действует лимит 60 запросов в минуту. Разные ключи в одном аккаунте могут иметь разные лимиты, поэтому сервису с высокой нагрузкой можно выдать более высокий RPM, чем разовой интеграции.

Когда ключ превышает свой лимит RPM, запрос завершается с HTTP-статусом 429 Too Many Requests, а в message указывается, что лимит частоты запросов превышен. Счетчики лимитов сбрасываются в скользящем окне в одну минуту.

Обработка ограничений частоты запросов

При 429 (и при временных 5xx) делайте паузу и повторяйте запрос. Поскольку окно составляет одну минуту, хорошо работает экспоненциальная задержка, которая начинается примерно с одной секунды и постепенно увеличивается:

async function checkWithRetry(content, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch('https://api.discuse.com/api/v2/check', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': process.env.DISCUSE_API_KEY
      },
      body: JSON.stringify({ content })
    });

    if (response.status === 429 || response.status >= 500) {
      const delay = 1000 * Math.pow(2, attempt); // 1s, 2s, 4s
      await new Promise(resolve => setTimeout(resolve, delay));
      continue;
    }

    return response.json();
  }
  throw new Error('Max retries exceeded');
}

Какие ответы с ошибками я могу получить?

Ситуация	HTTP-статус
Некорректный запрос (пустой контент, текст длиннее 10 000 символов, слишком много URL)	`400` валидация запроса
Отсутствующий или недействительный ключ API	`401`
Превышен лимит частоты запросов для ключа	`429`
Исчерпана квота расчетного периода	`200` с `message` и `usage` (не статус ошибки)

Исчерпание квоты намеренно не считается HTTP-ошибкой: ответ /api/v2/check по-прежнему возвращает 200 с has_violations: false, message с описанием исчерпанной квоты и объектом usage, где указано api_requests_remaining: 0. Проверяйте эти поля, а не полагайтесь только на код статуса. Ошибки аутентификации возвращают 401, ограничения частоты запросов — 429, а ошибки валидации запроса — 400. Полный список смотрите в справочнике Коды ошибок и ответов.

Управление несколькими ключами

Для больших команд или сложных приложений может понадобиться несколько ключей API:

Сценарии использования нескольких ключей

Ключи по средам: отдельные ключи для разработки, staging и production
Ключи по сервисам: разные ключи для разных микросервисов
Ключи по командам: разделение использования по командам для внутреннего биллинга
Временные ключи: краткосрочные ключи для подрядчиков или интеграций

Дальнейшие шаги

Краткое руководство - Выполните первый вызов API
Анализ текста - Узнайте о распознавании тональности
Масштабирование модерации контента - Шаблоны реализации для высоких нагрузок