AdPump — OAuth в API Яндекс Директа: токены, роли, Client-Login, IP whitelist

OAuth и доступ к API Яндекс Директа: пошаговая настройка и заголовки запросов.

Коротко: OAuth 2.0, заголовки Authorization и Client-Login, роли в кабинете.

← Каталог API Директа · Введение · Версии API · Сервисы v5 · Лимиты и баллы · Ограничения · Кампании · Группы и объявления · Ключи и ставки · Минус-фразы и площадки · Отчёты · Песочница · Агентства · Примеры JSON · Ошибки · Автоматизация · Документация Яндекса

Содержание

OAuth flow
Токен
Заголовки
Роли
IP whitelist
Client-Login
Обновление токена

OAuth flow — пошагово

Для доступа к API Директа нужно зарегистрировать OAuth-приложение на oauth.yandex.ru и получить токен от владельца аккаунта Директа.

Регистрация приложения. Создайте приложение, укажите Redirect URI, добавьте доступ к API Директа (scope direct:api).
Запрос авторизации. Перенаправьте пользователя на страницу Яндекса для подтверждения доступа.
Получение authorization code. После согласия пользователя Яндекс перенаправит на Redirect URI с параметром code.
Обмен code на access_token. POST-запрос к OAuth-серверу с grant_type=authorization_code.
Использование токена. Передавайте Authorization: Bearer <access_token> в каждом запросе к API.
Обновление. Перед истечением обновите токен через refresh_token.

GET https://oauth.yandex.ru/authorize?response_type=code
    &client_id=<client_id>
    &redirect_uri=<redirect_uri>
    &scope=direct:api

POST https://oauth.yandex.ru/token

Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=<code>&client_id=<client_id>&client_secret=<secret>

Документация по авторизации.

На oauth.yandex.ru укажите Redirect URI и разрешённые IP-адреса сервера, с которого будут идти запросы к API.

Храните refresh_token безопасно на сервере; не передавайте токены третьим лицам и не логируйте полностью.

Токен доступа

Authorization: Bearer y0_AgAAAAAAxxx...

Accept-Language: ru

access_token привязан к аккаунту Директа, который выдал разрешение. Срок действия — ограничен; храните refresh_token для автоматического обновления. При ошибке 53 — токен недействителен или отозван (коды ошибок).

Обязательные и рекомендуемые заголовки

Заголовок	Обязательность	Описание
Authorization	Да	Bearer <access_token>
Content-Type	Да	application/json; charset=utf-8
Accept-Language	Рекомендуется	ru — тексты ошибок на русском
Client-Login	Для агентств	Логин клиента
Use-Operator-Units	Для агентств	true — списание баллов с агентства

Роли в кабинете Директа

Роль	Доступ через API	Заголовки
Владелец	Полный доступ к своему аккаунту	Authorization
Представитель	Управление клиентскими аккаунтами	Authorization + Client-Login
Агентство	Все клиенты агентства	Authorization + Client-Login + Use-Operator-Units
Наблюдатель	Только чтение	Authorization + Client-Login

Подробнее о работе агентств: Агентства.

IP whitelist

В настройках OAuth-приложения на oauth.yandex.ru укажите разрешённые IP-адреса серверов, с которых будут выполняться запросы к API.

Добавьте статический IP сервера или диапазон для cloud-инстансов.
Запросы с неразрешённого IP будут отклонены.
При смене хостинга обновите whitelist заранее.
Для локальной разработки можно временно добавить домашний IP.

Client-Login

Authorization: Bearer <access_token>

Client-Login: client-company-login

Accept-Language: ru

Заголовок Client-Login обязателен, если токен выдан агентству или представителю, а запрос выполняется к аккаунту клиента. Без него — ошибка 54. Список клиентов: agencyclients.get (Агентства).

Обновление токена

POST https://oauth.yandex.ru/token

Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=<refresh_token>&client_id=<client_id>&client_secret=<secret>

Рекомендуется обновлять токен заранее истечения (за 1–2 часа до expiry). Храните refresh_token безопасно — не в клиентском коде и не в логах.

Перейти в инструмент