Авторизація за допомогою OAuth 2.0

Для інтеграції стороннього застосунку з eSputnik ми рекомендуємо налаштувати авторизацію за допомогою OAuth 2.0 .

OAuth 2.0 — це протокол авторизації, що дозволяє стороннім застосункам отримувати безпечний доступ до певних даних та можливостей eSputnik, не надаючи користувацькі облікові дані та API-ключі.

Надання прав доступу до акаунту eSputnik

З OAuth 2.0 ви можете обмежити доступ до ваших ресурсів у eSputnik. Наприклад:

• Stripo.email дозволяє лише експортувати шаблони листів до eSputnik.
• CRM (наприклад, AmoCRM) дозволяє лише додавати та редагувати контакти в eSputnik, коли вони змінюються у CRM. Або CRM також може отримувати дані про активність контактів та відображати їх у себе.
• CMS (наприклад, Wix) дозволяє лише використовувати стандартні форми підписки, щоб додавати підписників безпосередньо до eSputnik.

Доступ до ресурсів eSputnik визначається набором дозволів (scope), що задається при реєстрації застосунку. Нижче наведено доступні варіанти та відповідні методи API:

📘

Зверніть увагу

Якщо ви зміните область доступу застосунку після його реєстрації, вже видані токени продовжать працювати зі старим набором дозволів. Щоб отримати токен з оновленими правами, користувач має пройти повторну авторизацію.

Реєстрація, редагування та видалення застосунку в eSputnik

Перед тим, як почати інтегруватися за допомогою OAuth 2.0, зареєструйте свій застосунок в eSputnik.

Реєстрація застосунку

1. Натисніть назву вашої організації у верхньому правому куті та виберіть вкладку Для партнерів.

2. Натисніть кнопку Зареєструвати застосунок.

3. Надайте інформацію про застосунок:

• Назва
• Callback URL — адреса, на яку сервіс буде перенаправляти користувача після авторизації або відмови в авторизації вашого застосунку (ви можете створити застосунок без Callback URL та вказати його пізніше)
• Виберіть області доступу

4. Натисніть Зареєструватися.

Після реєстрації застосунку йому буде присвоєно ID клієнта (Client ID) та клієнтський ключ (Client Secret). Запишіть їх у надійному та безпечному сховищі.

5. Налаштуйте зовнішній вигляд форми авторизації:

• Натисніть Редагувати;

• Перейдіть на вкладку Форма авторизації;
• У разі потреби введіть назву застосунку;
• Завантажте логотип: максимальний розмір JPG, GIF або PNG – 1 МБ; співвідношення сторін, що рекомендується, — 1:1 (96×96 пікселів); зображення більшого розміру будуть обрізані до 100% ширини та вирівняні по центру.

Після реєстрації застосунку на вкладці Для партнерів з'явиться вікно з інформацією про нього.

Натисніть три крапки, щоб переглянути форму авторизації або видалити застосунок. Після видалення всі ключі/токени/інтеграції стануть недійсними.

Інтеграція з OAuth 2.0

📘

Зверніть увагу

Реалізація підтримана лише для застосунків, що мають серверну частину, тобто response_type=code.

1. Авторизація

Відправте GET-запит на URL-адресу авторизації https://uaa.esputnik.com/uaa/oauth/authorize.

Запит має містити ID клієнта, що ви отримали при реєстрації застосунку в eSputnik.

Формат запиту:

https://uaa.esputnik.com/uaa/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_CALLBACK_URL

Параметри запиту:

• response_type=code — вказує, що це запит сторінки авторизації з полями для введення логіна та пароля
• client_id — Client ID, отриманий при реєстрації застосунку
• redirect_uri — Callback URL, вказаний при реєстрації застосунку

В результаті з'явиться вікно авторизації.

Введіть логін та пароль облікового запису eSputnik та підтвердьте доступ.

Запит буде перенаправлено на Callback URL із кодом, що використовуватиметься для отримання токенів.

HTTP/1.1 302 Found
Location: http://YOUR_CALLBACK_URL?code=YOUR_CODE

2. Отримання токенів авторизації та оновлення

Відправте POST-запит на URL-адресу токена доступу https://uaa.esputnik.com/uaa/oauth/token.

Формат запиту:

https://uaa.esputnik.com/uaa/oauth/token?grant_type=authorization_code&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&code=YOUR_CODE&redirect_uri=YOUR_CALLBACK_URL

Автентифікація запиту — Basic Auth: username — ваш Client ID, password — ваш Client Secret.

Параметри запиту:

• grant_type=authorization_code — вказує, що це запит на отримання access token
• client_id — Client ID, отриманий при реєстрації застосунку
• client_secret — Client Secret, отриманий при реєстрації застосунку
• code — код авторизації, отриманий на попередньому кроці
• redirect_uri — Callback URL, вказаний при реєстрації застосунку

У відповіді ви отримаєте токен для доступу до API eSputnik (access_token) та токен для оновлення токена доступу (refresh_token).

Формат відповіді:

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "bearer",
  "refresh_token": "YOUR_REFRESH_TOKEN",
  "scope": "UseRestApi",
  "expires_in": 172800
}

📘

Примітка

За замовчуванням термін дії access token — 48 годин, refresh token — 30 днів. Відлік починається з моменту створення токена.

3. Звернення до API

Для звернення до API eSputnik передавайте access token у заголовку кожного запиту:

Authorization: Bearer <YOUR_ACCESS_TOKEN>

Доступні методи API визначаються набором дозволів (scope), заданим для застосунку при реєстрації.

4. Оновлення токена

Токен можна оновити в будь-який момент. Після оновлення старий access token стає недійсним — використовувати можна лише новий.

Відправте POST-запит на URL-адресу токена доступу https://uaa.esputnik.com/uaa/oauth/token.

Формат запиту:

https://uaa.esputnik.com/uaa/oauth/token?grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

Автентифікація запиту — Basic Auth: username — ваш Client ID, password — ваш Client Secret.

Параметри запиту:

• grant_type=refresh_token — вказує, що це запит на оновлення токена
• refresh_token — токен оновлення, отриманий на кроці 2 (або на кроці 4, якщо оновлення виконується повторно)
• client_id — Client ID, отриманий при реєстрації застосунку
• client_secret — Client Secret, отриманий при реєстрації застосунку

У відповіді ви отримаєте новий access_token та новий refresh_token, який потрібно використати при наступному оновленні.

5. Тестування авторизації

Відправте GET-запит на URL https://esputnik.com/api/v2/version з авторизацією у вигляді заголовка Authorization: Bearer <YOUR_ACCESS_TOKEN>.

У відповіді ви маєте побачити поточну версію API та версію API-протоколу.

Приклад авторизації за допомогою Python

import requests, json

authorize_url = "https://uaa.esputnik.com/uaa/oauth/authorize"
token_url = "https://uaa.esputnik.com/uaa/oauth/token"
callback_uri = "http://my_host:8081/test/callback"
protected_api_contacts = "https://esputnik.com/api/v1/contacts"

client_id = 'YOUR_CLIENT_ID'
client_secret = 'YOUR_CLIENT_SECRET'

authorization_redirect_url = authorize_url + '?response_type=code&client_id=' + client_id + '&redirect_uri=' + callback_uri
print("go to the following url on the browser and enter the code from the returned url: ")
print("---  " + authorization_redirect_url + "  ---")
authorization_code = input('code: ')

data = {'grant_type': 'authorization_code', 'code': authorization_code, 'redirect_uri': callback_uri}
print("requesting access token")
access_token_response = requests.post(token_url, data=data, verify=False, allow_redirects=False, auth=(client_id, client_secret))
print("response")
print(access_token_response.headers)
print('body: ' + access_token_response.text)

tokens = json.loads(access_token_response.text)
access_token = tokens['access_token']
print("access token: " + access_token)

api_call_headers = {'Authorization': 'Bearer ' + access_token}
api_call_response = requests.get(protected_api_contacts, headers=api_call_headers, verify=False)
print(api_call_response.text)

Підключені застосунки

Інтегровані застосунки відображаються на вкладці Підключені застосунки у налаштуваннях вашої організації. Щоб відключити застосунок, натисніть на три точки навпроти його назви та виберіть відповідну опцію.