Как авторизоваться в API

Типы пользовательских аккаунтов и доступ к данным

В myTarget существует несколько типов аккаунтов, позволяющих решать различные задачи.

  1. Прямой рекламодатель – advert. Это аккаунт физического или юридического лица, которое самостоятельно управляет своими рекламными кампаниями и имеет прямой договор с myTarget. Данный тип пользователя может полноценно работать с системой: размещать рекламные кампании, управлять ими, получать статистику и т.д.. Обратите внимание, что доступ к API предоставляется только юридическим лицам, у которых заключен договор с myTarget.
  2. Агентство – agency. Этот тип пользователя соответствует реальному рекламному агентству, которое обслуживает своих клиентов. В myTarget данные изолированы между аккаунтами вне зависимости от связи между ними. То есть доступ к данным агентства может получить только само агентство, а к данным клиента агентства – только клиент. Поэтому учётная запись агентства позволяет управлять своими клиентами и финансами, но для размещения рекламы по каждому клиенту, представителю агентства необходимо авторизоваться от имени клиента. В интерфейсе пользователь агентства может просто перейти в кабинет клиента по ссылке и получить доступ к его данным. В API это сделать также достаточно легко: нужно получить токен для работы с данными клиента. Для этого потребуется только API-ключ агентства и логин клиента.
  3. Менеджер агентства – manager. Это сотрудник агентства, который может вести нескольких клиентов этого агентства. Агентство самостоятельно выбирает, какие права будут доступны менеджеру: только чтение, управление рекламой и/или управление финансами. При этом, так же, как и агентству, менеджеру необходимо авторизоваться от имени клиента для управления его аккаунтом.
  4. Клиент агентства – agency_client. Это рекламодатель, кампаниями которого управляет агентство или, возможно, назначенный менеджер. Аккаунт позволяет производить те же действия, что и аккаунт прямого рекламодателя, но данным аккаунтом управляют сотрудники агентства. Обратите внимание, что API-ключи не предоставляется для аккаунтов клиентов агентств. Таким образом получить доступ через API к данным клиента можно только с помощью агентского API-ключа.

В зависимости от типа аккаунта следует использовать различную последовательность авторизации для доступа к тем или иным ресурсам. Тип аккаунта можно всегда узнать из запроса https://target.my.com/api/v2/user.json – в поле "type" будут перечислены значения.

Краткое описание методов авторизации: https://target.my.com/adv/api-marketing/doc/authorization

Общие принципы авторизации

Для аутентификации и авторизации в API myTarget используется протокол OAuth2, в соответствии с которым реализованы три различные схемы авторизации:

Процесс авторизации сводится к получению токена доступа (access token), который определяет ваши права и возможности, и в дальнейшем должен указываться при запросах к ресурсам пользователя. Для клиентских схем (Client Credentials Grant и Agency Client Credentials) токен выдаётся при предоставлении в запросе "client_id" и "client_secret". Для схемы Authorization Code Grant токен выдаётся при предоставлении кода, полученного приложением после того, как пользователь подтвердит, что готов дать данному приложению доступ к управлению своими данными.

При работе с токенами необходимо учитывать время их жизни. При получении токена, в ответе помимо самого access token, будут присутствовать поля "expires_in" и "refresh_token". Первое указывает на время жизни токена в секундах. В API myTarget стандартное время жизни равно 86400 секунд, что соответствует одним суткам. В течение всего этого периода вы можете делать различные запросы к API с использованием этого токена. По истечению срока жизни на запрос вернётся ошибка, сообщающая, что токен более не действителен.

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

POST /api/v2/oauth2/token.json HTTP/1.1
Host: target.my.com
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token={refresh_token}&client_id={client_id}&client_secret={client_secret}

Запрос на обновление токена имеет одинаковую структуру вне зависимости от того, с помощью какой из схем авторизации изначально был получен токен. Но параметры "client_id" и "client_secret" должны соответствовать тем, которые были указаны при получении токена.

Стандартный ответ:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
  "access_token": "{new_access_token}",
  "token_type": "bearer",
  "scope": "{scope}",
  "expires_in": "86400",
  "refresh_token": "{refresh_token}"
}

Обновление токена не создаёт его новую копию, а только изменяет строковый ключ. Обратите внимание, что необоснованная генерация новых токенов (вместо обновления) расценивается как некорректная работа с API и может привести к запрету доступа к API.

Для каждой связки clientId - user одновременно может существовать не более 5 токенов, вне зависимости от статуса токена. То есть, если один и тот же аккаунт подключен к двум различным приложениям, то каждое из приложений сможет выписать по 5 токенов для данного аккаунта. Лимит фиксирован и не может быть увеличен ни в каких случаях. 

Токены автоматически удаляются по истечении месяца неактивности (указано в поле "expires_in"). 

По достижении лимита в ответ на попытку получить новый токен будет возвращена ошибка с HTTP-кодом 403. Для избежания подобных ошибок, необходимо корректно обновлять выписанные токены и не создавать их избыточные копии.

Подробнее об операциях с токенами (обновление, удаление, устранение ошибок и т.д.) можно прочитать в этой статье.

Рекомендуется к прочтению:

OAuth 2.0 простым и понятным языком (https://habrahabr.ru/company/mailru/blog/115163/)

Oauth 2.0 спецификация https://tools.ietf.org/html/rfc6749

Авторизация прямого рекламодателя

Для авторизации прямого рекламодателя используется схема Client Credentials Grant.

Чтобы получить токен доступа, нужно послать запрос вида:

POST /api/v2/oauth2/token.json HTTP/1.1
Host: target.my.com
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}

Ключи "client_id" и "client_secret" можно получить, отправив заявку на подключение к API.

В случае успешного выполнения ответ будет выглядеть следующим образом:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
  "access_token": "{access_token}",
  "token_type": "bearer",
  "scope": "{scope}",
  "expires_in": "86400",
  "refresh_token": "{refresh_token}"
}

Далее полученный токен можно использовать при отправке запросов к API myTarget. Значение токена указывается в заголовке Authorization. Перед токеном должен быть указан тип Bearer:

GET /api/v2/campaigns.json HTTP/1.1
Host: target.my.com
Authorization: Bearer {access_token}

Авторизация для агентств

Авторизация самого агентства аналогична авторизации прямого рекламодателя, но для получения доступа к данным клиента требуется также выполнить авторизацию по схеме Agency Client Credentials Grant. Для получения доступа к данным клиента агентства необходимо выполнить следующие шаги:

  1. Выполнить авторизацию агентства по схеме Client Credentials Grant. С полученным в результате авторизации токеном, можно выполнять следующие операции от имени агентства: управление клиентами: создание, редактирование, удаление, а также управление финансами – переводы денег между агентством и клиентами.
  2. Запросить список клиентов агентства, выполнив запрос к clients.json с помощью токена, полученного на первом шаге. Подробнее о ресурсе можно прочитать этой статье.
  3. Авторизоваться под необходимым клиентом с помощью схемы Agency Client Credentials Grant, указав "client_id" и "client_secret" агентства, а также "agency_client_name" (поле username из запроса clients.json) – логин клиента агентства, для которого запрашивается токен:

    POST /api/v2/oauth2/token.json HTTP/1.1
    Host: target.my.com
    Content-Type: application/x-www-form-urlencoded
    grant_type=agency_client_credentials&client_id={client_id}&client_secret={client_secret}&agency_client_name={client_username}

Ответ будет таким же, как и при запросе с использованием схемы Client Credentials Grant.

С помощью токена, полученного на третьем шаге, можно управлять аккаунтом клиента: создавать и редактировать баннеры, кампании, получать статистику, управлять списками и т.д.

Для получения доступа к данным другого клиента достаточно повторить третий шаг для этого клиентского логина.

Этот же алгоритм действий выполняется и при авторизации с помощью ключей учётной записи менеджера. Но есть два отличия. Первое в том, что для получения списка клиентов менеджера необходимо использовать запрос к https://target.my.com/api/v2/manager/clients.json. Второе же заключается в правах учётной записи. Если агентство выдало менеджеру права «только чтение», то он не сможет использовать никакие запросы на создание, редактирование или удаление каких-либо объектов. В случае выдачи прав «Создание и редактирование кампаний» менеджер сможет управлять рекламными кампаниями клиентов. Права «Доступ к счёту» позволяют менеджеру делать переводы денег. Права менеджера устанавливает агентство в личном кабинете myTarget.

Схема Agency Client Credentials Grant может также использоваться для авторизации рекламных платформ, действующих от имени агентства или менеджера. Подробнее об этой возможности можно прочитать в этой статье.

Авторизация для приложений

Приложения, которые предоставляют сервис по работе с myTarget для сторонних клиентов, должны использовать схему Authorization Code Grant.

Для получения токена доступа к информации аккаунта, приложение должно получить разрешение на это от владельца аккаунта. Вне зависимости от типа аккаунта, к которому получается доступ, процесс выглядит следующим образом:

1. Приложение в собственном интерфейсе предлагает пользователю предоставить доступ и, при согласии пользователя, направляет его на страницу https://target.my.com/oauth2/authorize, передавая в параметрах:

  • свой "client_id".
  • state – символьный токен, генерируемый на стороне приложения. В дальнейшем этот токен в неизмененном виде будет возвращён приложению, которому необходимо будет проверить отправленное и возвращенное значение на идентичность, что обеспечит дополнительную безопасность. Токен может принимать любые значения.
  • scopes – набор запрашиваемых прав. Подробнее о возможных правах: здесь.

2. Если пользователь на странице https://target.my.com/oauth2/authorize разрешает доступ приложению, то сервис перенаправляет его на страницу приложения, которую вы указывали как парамент "redirect_uri" при запросе на выдачу вашему приложению прав доступа к схеме  Authorization Code Grant. В параметрах также передаётся "state", отправленный приложением на шаге 1, и "code" – временный токен, который необходимо будет обменять на токен доступа. Время жизни токена code – 1 час.

3. Приложение обменивает code на access token с помощью запроса

POST /api/v2/oauth2/token.json HTTP/1.1
Host: target.my.com
Content-Type: application/x-www-form-urlencoded

Если с помощью описанного алгоритма был получен токен доступа для аккаунта агентства или менеджера, то для получения токена аккаунтов клиентов агентства необходимо воспользоваться тем же алгоритмом, который описан в разделе «Авторизация для агентств». То есть вам необходимо будет использовать схему Agency Client Credentials Grant, но с запросом вида:

POST /api/v2/oauth2/token.json HTTP/1.1
Host: target.my.com
Content-Type: application/x-www-form-urlencoded
grant_type=agency_client_credentials&client_id={client_id}&client_secret={client_secret}&agency_client_name={client_username}&access_token={agecny_access_token}

В этом запросе приложению нужно будет указать помимо собственных "client_id" и "client_secret" ещё и "access_token", полученный после предоставления агентством доступа для вашего приложения.