Авторизация с помощью 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 ограничен предоставленными при регистрации приложения правами:

• Полный доступ до API
• Доступ к событиям
• Доступ к событиям и контактам
• Доступ к сообщениям

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

Группы API-методов по функциям в системе

1. Общие методы

Методы из этой группы не требуют специальных разрешений, нужна только авторизация аккаунта eSputnik.

1.1 Информация о версии протокола:

• GET version

1.2 Информация об аккаунте:

• GET account/info
• GET balance
• GET subscriptions
• GET addressbooks

1.3 Управление сообщениями

• POST messages/email
• GET messages/email
• GET messages/email/{id}
• DELETE messages/email/{id}
• PUT messages/email/{id}
• DELETE messages/email/{id}/{language}
• PUT messages/email/{id}/{language}
• GET messages/email/{id}/viewLink
• GET messages/sms
• GET messages/sms/{id}

1.4 Управление интерфейсами

• GET interfaces/email
• GET interfaces/sms

1.5 Статистика

• GET callouts/sms
• GET contact/token/activated/{app_uuid}/{token_id}
• PUT contact/token/activated/{app_uuid}/{token_id}
• PUT interactions/{interaction_id}/status

2. Методы обновления контактов и групп

Обычно интеграция предполагает обновление контактов, а не их считывание. Поэтому во избежание утечки данных можно ограничить права доступа только обновлением контактов.

• POST contacts
• POST contacts/upload
• GET importstatus/{sessionId}
•  POST contact
• PUT contact/{id}
• DELETE contact/{id}
• PUT contact/{id}/subscriptions
• POST contact/subscribe
• POST emails/unsubscribed/add
• POST emails/unsubscribed/delete
• POST group/{id}/contacts/detach

3. Методы для чтения контактов и групп
 

• GET contacts
• GET contact/{id}
• GET contacts/email
• GET contact/{id}/subscriptions
• GET groups
• GET group/{id}/contacts

4. Методы для получения данных об активности контактов

• GET contacts/activity

5. Методы для управления событиями

• POST event
• POST past_events
• DELETE past_events

6. Методы для управления сообщениями

• POST message/{id}/smartsend
• POST message/{id}/send OLD
• GET message/status
• POST message/email
• GET message/email/status OLD
• POST message/sms
• GET message/sms/status OLD
• POST message/viber
• GET message/viber/status OLD
• POST broadcast
• GET broadcast/{broadcast_id}
• DELETE broadcast/{broadcast_id}
• GET broadcasts

Регистрация, редактирование и удаление приложения в 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

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

Отправьте GET-запрос на URL авторизации https://uaa.esputnik.com/uaa/oauth/authorize.

Запрос должен содержать ID клиента, полученный при регистрации приложения в eSputnik.

Формат запроса:

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

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

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

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

> HTTP/1.1 302 Found
> Location: http://awesome_host/callback?code=YOUR_CODE

2. Получение токенов авторизации и обновления

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

Запрос должен содержать:

• ID клиента и клиентский ключ, полученный при регистрации приложения в eSputnik
• код, который вы получили при авторизации

Формат запроса:

https://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

В ответе вы получите токен для доступа к API eSputnik (Access Token) и токен для обновления токена доступа (Refresh Token).

Формат ответа:

{
  "access_token": "YOUR_TOKEN",
  "token_type": "bearer",
  "refresh_token": "YOUR_REFRESH_TOKEN",
  "scope": "UseRestApi",
  "expires_in": 172541
}

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

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

Запрос должен содержать:

• ID клиента и клиентский ключ, полученный при регистрации приложения в eSputnik
• код, который вы получили при авторизации
• последний полученный вами токен обновления

Формат запроса:

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

Ответ содержит новый токен доступа и новый токен обновления, который должен использоваться при следующем обновлении токена доступа.

4. Тестирование авторизации

Отправьте GET-запрос на URL https://esputnik.com/api/v2/version с авторизацией в виде заголовка Authorization: Bearer <YOUR_ACCESS_TOKEN>.

В ответе вы должны увидеть текущую версию API и версию API-протокола.

Пример авторизации с помощью Python

import requests, json
import subprocess
import sys
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"
test_api_url = protected_api_contacts
client_id = 'daf4ba310fe44961fabc80ce2d1f67cd'
client_secret = '6c573654f43bc05c13c6b0d0bc65d6a65fe38a09f84e84ac37c3210e78b06b3e'
#step A - simulate a request from a browser on the authorize_url - will return an authorization code after the user is
# prompted for credentials.
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: ')
# step I, J - turn the authorization code into a access token, etc
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)
# we can now use the access_token as much as we want to access protected resources.
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.post(test_api_url, headers=api_call_headers, verify=False, json=json)
api_call_response = requests.get(test_api_url, headers=api_call_headers, verify=False)
print(api_call_response.text)

Подключенные приложения

Интегрированные приложения отображаются на вкладке “Подключенные приложения” в настройках вашей организации. Чтобы отключить приложение, нажмите на три точки напротив его названия и выберите соответствующую опцию.