Аутентификация

Обзор

Все эндпоинты /v1/* требуют аутентификации через заголовок Authorization с использованием Bearer-токена:

Authorization: Bearer <token>

API-ключи

API-ключи являются рекомендуемым методом аутентификации для серверного и программного использования. Они долгоживущие, легко управляемые и не требуют внешних SDK.

Создание API-ключа

API-ключи можно создать двумя способами:

Через панель управления:

1. Перейдите в Панель управления > Настройки > API-ключи.
2. Нажмите Создать API-ключ.
3. Введите описательное имя и выберите срок действия.
4. Скопируйте ключ немедленно.

Через API:

curl -X POST https://api.docmap.io/v1/api-keys \
  -H "Authorization: Bearer <existing-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Server",
    "expiresIn": "90d"
  }'

Формат ключа

API-ключи имеют следующий формат:

dm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Длина ключей составляет 72 символа, и они всегда начинаются с префикса dm_live_.

Варианты срока действия

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

• 30 дней
• 60 дней
• 90 дней
• 1 год
• Бессрочный (без срока действия)

WARNING

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

Лимиты

Каждый аккаунт может иметь максимум 10 активных API-ключей одновременно. Отзывайте неиспользуемые ключи, чтобы освободить слоты.

Пример запроса

cURL

curl https://api.docmap.io/v1/extractions \
  -H "Authorization: Bearer dm_live_your_api_key"

TypeScript

const response = await fetch('https://api.docmap.io/v1/extractions', {
  headers: {
    'Authorization': `Bearer ${process.env.DOCMAP_API_KEY}`,
  },
})

Ответы при ошибках

Если аутентификация не удалась, API возвращает ответ 401 Unauthorized:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired authentication token."
  }
}

Распространенные причины:

• Отсутствует заголовок Authorization
• Некорректный токен (неправильный префикс или формат)
• Истекший API-ключ
• Отозванный API-ключ

Лучшие практики безопасности

DANGER

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

Следуйте этим рекомендациям для обеспечения безопасности ваших учетных данных API:

1. Храните ключи в переменных окружения -- Никогда не записывайте API-ключи непосредственно в исходный код. Используйте переменные окружения или менеджер секретов.

   # .env file (never commit this)
   DOCMAP_API_KEY=dm_live_your_api_key

   // Read from environment
   const apiKey = process.env.DOCMAP_API_KEY

2. Регулярно ротируйте ключи -- Создавайте новые ключи и выводите из эксплуатации старые по регулярному расписанию, даже если у вас нет оснований подозревать компрометацию.

3. Немедленно отзывайте скомпрометированные ключи -- Если ключ был случайно раскрыт (например, закоммичен в публичный репозиторий), отзовите его в Панель управления > Настройки > API-ключи немедленно и создайте замену.

4. Используйте минимально возможный срок действия -- Выбирайте срок действия, который балансирует между удобством и безопасностью. Для большинства производственных случаев 90 дней -- хороший вариант по умолчанию.

5. Используйте отдельные ключи для разных окружений -- Создавайте отдельные ключи для разработки, тестирования и продакшена. Это ограничивает зону поражения при компрометации одного ключа и упрощает ротацию ключей без простоев.

6. Добавьте файл .env в .gitignore -- Убедитесь, что файлы окружения никогда не попадают в систему контроля версий.

   # .gitignore
   .env
   .env.local
   .env.*.local