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

Безопасный доступ к API через систему ключей. Защитите свои запросы и контролируйте доступ к сервисам.

API-ключи

Что такое API-ключ?

API-ключ — это уникальная строка, которая идентифицирует вашего клиента при каждом запросе к API. Ключ привязан к вашему аккаунту и используется для:

• Идентификации вашего приложения
• Контроля лимитов и квот использования
• Отслеживания статистики запросов
• Обеспечения безопасности

Важно!

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

Формат ключа

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

vl_[environment]_[random_string]

Где environment может быть:

• test — для тестовых запросов
• live — для продакшн-окружения

Методы аутентификации

1. Заголовок x-api-key (рекомендуется)

Передавайте API-ключ в заголовке каждого HTTP-запроса:

curl -X GET "https://api.vialine.ru/api/v1/slots?date=2024-10-20" \
  -H "x-api-key: vl_live_1a2b3c4d5e6f7g8h9i0j" \
  -H "Content-Type: application/json"

Пример на JavaScript:

const response = await fetch('https://api.vialine.ru/api/v1/slots', {
  method: 'GET',
  headers: {
    'x-api-key': 'vl_live_1a2b3c4d5e6f7g8h9i0j',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();

2. Bearer Token

Альтернативный способ — использование Authorization заголовка с Bearer токеном:

curl -X GET "https://api.vialine.ru/api/v1/slots?date=2024-10-20" \
  -H "Authorization: Bearer vl_live_1a2b3c4d5e6f7g8h9i0j" \
  -H "Content-Type: application/json"

Пример на Python:

import requests

headers = {
    'Authorization': 'Bearer vl_live_1a2b3c4d5e6f7g8h9i0j',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.vialine.ru/api/v1/slots',
    headers=headers
)

data = response.json()

Рекомендации по безопасности

✓ Делайте

• Используйте переменные окружения (.env)
• Храните ключи на сервере, не в клиенте
• Регулярно ротируйте ключи
• Используйте HTTPS для всех запросов
• Мониторьте использование API

✗ Не делайте

• Не коммитьте ключи в Git
• Не встраивайте в клиентский JavaScript
• Не передавайте в URL параметрах
• Не используйте один ключ для разных сред
• Не делитесь ключами с третьими лицами

Пример правильного хранения (.env файл):

# .env.local
VIALINE_API_KEY=vl_live_1a2b3c4d5e6f7g8h9i0j
VIALINE_API_URL=https://api.vialine.ru

Добавьте .env.local в .gitignore

Обработка ошибок аутентификации

401 Unauthorized

API-ключ отсутствует или недействителен

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API ключ отсутствует или недействителен"
  }
}

403 Forbidden

Доступ к ресурсу запрещён (превышен лимит или недостаточно прав)

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Превышен лимит запросов. Попробуйте позже."
  }
}

429 Too Many Requests

Превышен rate limit (слишком много запросов за короткий период)

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Превышен лимит запросов",
    "retryAfter": 60
  }
}