Авторизація в API
Agency Client Credentials Grantвикористовується до роботи з даними своїх клієнтів агентств\менеджеров.
Перші дві схеми доступні кожному API-клієнту, доступ до схеми Authorization Code Grant надається лише за умови виконання умов.
Використовуючи будь-який з цих методів, буде отримано об'єкт Access Token, що містить ключі access_token та refresh_token. Ключем access_token має бути підписаний кожен запит до API:
Client Credentials Grant
Щоб отримати токен доступу, потрібно надіслати запит на вигляд:
У разі успішного виконання відповідь виглядатиме так:
Agency Client Credentials Grant
Ця схема протоколу OAuth2 не є стандартною. Вона була реалізована для того, щоб дати можливість агенціям та менеджерам створювати токени доступу для своїх клієнтів без підтвердження від клієнта. Схема дуже схожа на стандартну Client Credentials Grant за винятком того, що у запиті потрібно передавати додатковий параметр "agency_client_name" (username із запиту AgencyClients або ManagerClients):
Authorization Code Grant
Алгоритм отримання доступу виглядає так:
API-клієнт перенаправляє користувача на спеціальну сторінку https://target.my.com/oauth2/authorize, вказавши параметри "response_type" (зі значенням "code"), "state" (згенерований на стороні клієнта токен, використовується для запобігання CSRF - може містити довільний набір символів), свій "client_id" та список прав доступу "scope":
Отримавши параметр code, клієнт може запросити access_token для подальшої роботи з API від імені користувача. Для цього необхідно надіслати запит на /api/v2/oauth2/token.json, передавши параметри "grant_type" (зізначенням "authorization_code"), "code" (отриманий при зворотному редиректі на "redirect_uri" токен):
Отриманий токен доступу використовується для автентифікації запитів, що надсилаються в API від імені користувача:
Для отримання токенів клієнтів агентства або менеджера, що надав доступ, необхідно скористатися розширеною схемою Agency Client Credentials. Для цього крім параметра agency_client_name та інших, необхідно вказати отриманих токен агентства у параметрі access_token:
У разі успішного виконання запиту, у відповіді буде токен доступу для здійснення операцій від імені клієнта агентства або менеджера.
Scopes - права доступу
- read_ads - читання статистики та РК;
- read_payments - читання грошових транзакцій та балансу;
- create_ads - створення та редагування налаштувань РК, банерів, аудиторій (ставки, статус, націлення тощо).
Для користувачів-агентств та користувачів-представництв:
Робота з токенами
Ліміт на кількість токенів
Не вічні токени автоматично видаляються через місяць неактивності (вказано у полі "expires_in").
Після досягнення ліміту у відповідь на спробу отримати новий токен буде повернуто помилку з HTTP-кодом 403.
Щоб уникнути подібних помилок, необхідно коректно оновлювати виписані токени і не створювати надмірні копії.
Видалення токенів
При досягненні ліміту кількість токенів можна самостійно видалити всі токени конкретного користувача. Для цього використовується запит виду:
де "username" - це логін користувача, для якого потрібно видалити токени.
Термін дії access-токену
Кожен отриманий токен доступу за умовчанням є дійсним упротягом доби. Це вказує властивість "expires_in" у відповіді запит токена доступу. Обмежений термін життя дозволяє надійніше захистити значення "access_token". Навіть заволодівши значенням одного "access_token", зловмисник не зможе виконати запити з ним після закінчення терміну дії або після першого оновлення токена.
Менш безпечний спосіб - "вічні" токени доступу. Для отримання "access_token" без обмеження терміну дії необхідно додати GET-параметр "permanent=true" в запит створення або оновлення токена. Наприклад:
Оновлення токена доступу
В об'єкті токена Access Token також вказується ключ "refresh_token" - спеціальний токен для оновлення ключа access_token та продовження часу життя об'єкта. За це відповідає схема Refreshing an Access Token у протоколі OAuth2.
Запит на оновлення доступу:
Важливо враховувати, що оновлення токена не створює нового примірника: змінюється значення "access_token", старе значення ключа перестає працювати. Це може призвести до проблем при роботі з API у кілька потоків: два потоки можуть одночасно виявити, що токен закінчився і надіслати запит на оновлення. Запит, який прийшов першим, оновить токен і почне його використовувати, тоді як другий потік оновить токен ще раз, і перший потік намагатиметься використати токен, що вже не існує.
Одним із варіантів вирішення цієї проблеми є перехоплення помилки про неіснуючий токен у першому потоці та отримання токена заново із загального для потоків сховища – наприклад, бази даних, куди кожен потік записує токен після оновлення. Потрібно також врахувати, що запис у сховищі теж може бути конкурентним і використовувати, наприклад, блокування.
Іншим варіантом вирішення цієї проблеми може бути включення опціїоновлення "refresh_token" під час кожного оновлення "access_token". Тоді перший потік оновить і "access_token", і "refresh_token", а у другому потрібно обробити помилку про невідоме "refresh_token" і перечитати "access_token" зі сховища. Але при оновленні "refresh_token" потрібно обов'язково зберігати його останнє значення, інакше ви більше не зможете оновити "access_token", і доведеться виписувати новий. Цю опцію OAuth-клієнта зараз можна включити лише за запитом до служби підтримки.
Ще один варіант: превентивне оновлення всіх струменів, що минають. Він полягає в тому, що потрібно регулярно перевіряти, чи немає у вас токенів, що спливають, наприклад, у найближчі пів години, і оновлювати їх у фоновому процесі. Але якщо поєднувати його з оновленням в режимі реального часу в робочих процесах, все одно доведеться обробляти помилки через можливі конфлікти.
Помилки при використанні некоректних токенів
При викликі будь-якого методу API можуть повертатися різні помилки, пов'язані з некоректним значенням чи станом "access_token".
Такі помилки мають код 401 та загальну структуру: