Авторизационные токены
Авторизационный токен, или OAuth-токен, ― это специальный код, разрешающий доступ к данным конкретного пользователя. Для каждого пользователя Директа, от имени которого осуществляются запросы к API, необходимо получить отдельный токен.
Токен следует указывать в каждом запросе к API. По токену сервер Директа определяет, от имени какого пользователя приложение выполняет запрос и действительно ли пользователь разрешил этому приложению доступ к своим данным в Директе. Приложению доступны только те действия, которые доступны пользователю, для которого получен токен.
Подробная информация приведена в документации Яндекс.OAuth.
Регистрация приложения
Зарегистрировать приложение на сервисе Яндекс.OAuth достаточно один раз. При этом необходимо войти на Яндекс под логином разработчика приложения. Более подробная информация приведена в подразделе Регистрация на сервисе Яндекс.OAuth раздела Регистрация приложения.
Получение токена
- Получение токена вручную
-
На этапе отладки приложения вы можете вручную получить так называемый отладочный токен от имени тестового пользователя. См. раздел Отладочный токен документации Яндекс.OAuth.
- Получение токена в автоматическом режиме
-
При переходе к работе с данными реальных пользователей необходимо реализовать в приложении удобный для пользователей механизм получения токена. Чтобы получить токен, приложение должно открыть для пользователя специальную страницу Яндекс.OAuth — страницу запроса доступа. Пользователь авторизуется на Яндексе (под своим логином в Директе) и подтверждает доступ приложения к своим данным — нажимает кнопку «Разрешить». Яндекс.OAuth генерирует токен и передает его приложению в автоматическом режиме.
Яндекс.OAuth поддерживает несколько вариантов передачи токена, которые подходят для разных типов приложений: веб-сервис, настольное приложение (программа для компьютера), мобильное приложение и др. Процедура получения токена подробно описана в документации Яндекс.OAuth.
См. также пример на PHP, пример на Python.
- Какой режим получения токена выбрать?
-
В некоторых случаях допустимо использовать токен, полученный вручную, и после перехода к работе с данными реальных пользователей. Например:
если с приложением работает небольшое количество пользователей — представителей одного рекламодателя;
если приложение не взаимодействует с пользователем — например, скрипт обновляет ставки в автоматическом режиме.
Если же с приложением работают несколько рекламодателей или много пользователей с разными правами доступа, получать токен следует в автоматическом режиме.
Использование токена при вызове методов
Токен, полученный для пользователя, необходимо указывать в HTTP-заголовке Authorization при каждом запросе к API Директа от имени этого пользователя.
Если указан неверный токен, возвращается сообщение об ошибке с кодом 1002.
Прекращение действия токена
Ситуации, в которых токен становится недействительным и требуется получить новый токен, перечислены в разделе Отзыв токенов документации Яндекс.OAuth.
Для работы в приложении мы рекомендуем зарегистрировать в Директе отдельного представителя и получить для него токен. См. раздел Рекомендации по созданию представителей.