Аутентификация API и Bearer-токены

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

1. Зарегистрируйтесь и войдите в свою учетную запись Quote3D.
2. Сгенерируйте API-токен на своей панели управления во вкладке "Tokens".
3. Включите токен в ваши API-запросы. Поддерживаются Authorization: Bearer и X-API-Token:
   Authorization: Bearer YOUR_TOKEN_HERE
4. Сервер проверяет ваш токен и предоставляет доступ, если он действителен и не истек.

Области действия токенов

Область токена определяет, какие эндпоинты ему доступны. Вы выбираете её при создании токена и можете увидеть на странице «Токены» в панели.

• Полный доступ — вариант по умолчанию для серверного токена. Он достигает всех эндпоинтов, разрешённых вашим тарифом.
• Виджет — область для токена, встраиваемого в витрину. Она ограничена тем, что нужно встраиваемому виджету, и не даёт доступа к вебхукам, данным аккаунта, аналитике, использованию и лимитам.

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

Жизненный цикл токена

• Значение токена показывается один раз, при создании. Затем восстановить его нельзя — сразу сохраните в менеджере секретов. Если потеряли, обновите токен, чтобы получить новое значение.
• Токены можно создавать со сроком действия. Просроченный токен перестаёт работать и возвращает 401; панель показывает дату истечения каждого токена.
• Обновление токена выпускает новое значение и немедленно аннулирует прежнее. Разверните новое значение до обновления, поскольку выполняющиеся запросы со старым токеном начнут падать сразу же.
• Токен можно ограничить списком IP-адресов. Вызовы с любого другого адреса отклоняются с кодом 403 — частая неожиданность после переноса сервера или смены NAT-шлюза.
• Ваш тариф ограничивает число токенов. Бесплатные тарифы позволяют один серверный токен и один токен виджета.

Когда аутентификация не проходит

Отклонённый запрос возвращает стандартную оболочку ошибки с success: false и коротким сообщением. Ветвитесь по коду состояния HTTP, а не по тексту сообщения, который может быть переформулирован.

{
  "success": false,
  "error": "API token has expired"
}

• 401 — токен отсутствует, повреждён, истёк или отозван. Проверьте имя заголовка и то, что значение не обрезалось при копировании.
• 403 — токен действителен, но не разрешён для этого вызова. Обычные причины: ограничение области или белый список IP, не включающий вызывающую сторону.

Формат токена

Токены Quote3D являются учетными данными API в формате bearer. Клиенты должны рассматривать их как непрозрачные секреты и избегать зависимости от внутренней структуры токена.

JWT состоит из трех частей:

1. Заголовок: Указывает алгоритм подписи и тип токена.
2. Полезная нагрузка: Содержит данные пользователя и утверждения (например, ID пользователя, адрес электронной почты и время истечения срока действия).
3. Подпись: Проверяет, что токен не был подделан.

JWT выглядит следующим образом:

Для интеграций важно помнить простое правило: храните токен в безопасности, отправляйте его с каждым запросом и избегайте его разбора или раскрытия в клиентском коде, если интеграция явно не требует токен на стороне клиента.

Пример использования вашего токена

Вот как можно использовать ваш токен с помощью curl. Используйте один стиль заголовка аутентификации последовательно:

Или в API Playground вставьте ваш токен в модальное окно авторизации (значок замка), чтобы аутентифицировать вашу сессию. Вы также можете использовать X-API-Token в пользовательских интеграциях, если этот заголовок лучше подходит.