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

Токен доступа API — это уникальный идентификатор, присвоенный определенному проекту или нескольким проектам в вашем аккаунте. Он аутентифицирует ваш аккаунт для управления проектами через API, включая изменение аккаунта, отправку сообщений, редактирование проектов и т. д.

Типы токенов доступа API

Pushwoosh предоставляет два разных типа токенов доступа API: Server и Device.

Каждый тип токена действителен только для своей конкретной области API. Если используется неверный токен, произойдет ошибка аутентификации.

Токен Server API

Токен Server API используется со всеми методами API, за исключением тех, которые относятся к Device API. Он должен быть включен в тело запроса в поле auth.

Токен Device API

Токен Device API используется исключительно с методами Device API. Он должен быть включен в заголовки HTTP-запроса с использованием заголовка Authorization. Ниже приведен пример правильного формата заголовка:

Authorization: Token <device_api_token>

Замените <device_api_token> на фактическое значение вашего токена Device API.

Методы, требующие токен Device API

Следующие методы API требуют токен Device API для авторизации:

• registerDevice
• unregisterDevice
• deleteDevice
• setTags
• getTags
• setBadge
• applicationOpen
• pushStat
• messageDeliveryEvent
• registerUser
• deleteUser
• postEvent
• registerEmail
• deleteEmail
• setEmailTags
• registerEmailUser
• getInboxMessages
• inboxStatus

Создание и управление токенами доступа API

Вы можете просматривать, создавать и управлять своими токенами доступа API в разделе API Access в панели управления Pushwoosh. Чтобы получить к нему доступ, перейдите в Settings → API Access.

По умолчанию каждый аккаунт включает токен под названием Pushwoosh Demo App, который настроен как серверный токен.

Создание нового токена доступа API

Чтобы создать новый токен доступа API:

1. Перейдите в раздел API Access в панели управления.

2. Нажмите Generate New Token.

3. В появившемся окне выберите тип токена:

   • Server используется для большинства методов API (за исключением методов Device API).

   • Device используется только для методов Device API.

4. Введите имя для токена.

5. Нажмите Generate, чтобы создать токен.

Важно: Убедитесь, что вы предоставили токену доступ к нужному приложению в вашей панели управления Pushwoosh. Узнать больше

Новый токен появится в списке API Access. Оттуда вы можете скопировать его значение для использования в запросах API или управлять его правами доступа по мере необходимости.

Управление токеном

Чтобы управлять существующим токеном API, нажмите на меню из трех точек (⋮) рядом с записью токена в разделе API Access.

Доступны следующие опции:

Предоставить доступ ко всем проектам

Предоставляет токену доступ ко всем проектам в вашем аккаунте. Это позволяет ему полностью использовать API во всех проектах.

Совет

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

Отозвать доступ ко всем проектам

Удаляет доступ токена ко всем проектам в вашем аккаунте. Токен больше не сможет использовать API до тех пор, пока доступ не будет предоставлен снова.

Редактировать токен

Открывает экран Edit API Token Permissions, где вы можете:

• Изменить имя токена

• Скопировать значение токена

• Выбрать, к каким проектам токен имеет доступ, выбирая или отменяя их выбор в списке

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

• Установить разрешенные IP-адреса, с которых можно использовать токен (только для токенов Server)

Вкладка Permissions также показывает время последнего использования токена и количество отклоненных вызовов за последние 7 и 30 дней.

После внесения изменений нажмите Save, чтобы применить их.

Совет

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

Проверить журнал использования токена

Откройте вкладку Usage journal на экране Edit API Token Permissions, чтобы просмотреть каждый вызов API, сделанный с помощью токена за последние 90 дней. Выберите результат (Any outcome, Accepted, Completed, Refused: IP address, Refused: no rights) и диапазон дат, затем нажмите Apply, чтобы отфильтровать список. Нажмите Export CSV, чтобы загрузить отфильтрованный журнал в виде CSV-файла.

Удалить токен

Безвозвратно удаляет токен из вашего аккаунта.

Осторожно

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

Авторизация запросов API

Для авторизации запросов API используйте правильный тип токена доступа API в зависимости от типа вызываемого метода API:

Для методов Server API

Включите токен в поле “auth” тела запроса:

Пример:

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "yxoPUlwqm…………pIyEX4H", // вставьте сюда ваш серверный токен
    "notifications": [{
      "send_date": "now",
      "content": "Hello world"
    }]
  }
}

Для методов Device API

Используйте токен Device. Включите его в заголовок HTTP-запроса в следующем формате:

Authorization: Token <device_api_token>

Замените <device_api_token> на фактическое значение вашего токена.

Осторожно

Убедитесь, что тип токена соответствует используемому методу API. Если токен не соответствует требуемому типу, запрос вернет ошибку аутентификации.

Ограничение токена по определенным IP-адресам

Токен Server может быть ограничен списком разрешенных исходных IP-адресов. Когда список установлен, Pushwoosh принимает запросы API, сделанные с этим токеном, только с совпадающего адреса. У токенов Device такой опции нет.

Откройте Edit token для токена Server и введите адреса в Allowed IP addresses:

• Добавьте до 50 записей, IPv4 или IPv6, каждая в виде отдельного адреса (203.0.113.7) или диапазона CIDR (203.0.113.0/24).
• Отдельный адрес сохраняется как диапазон полной длины, например, 203.0.113.7 становится 203.0.113.7/32.
• Диапазон канонизируется до своего сетевого адреса, например, 203.0.113.7/24 становится 203.0.113.0/24.
• 0.0.0.0/0 и ::/0 отклоняются, так как они будут соответствовать любому адресу и не обеспечат ограничения.
• Оставьте список пустым, чтобы токен можно было использовать с любого адреса. Это значение по умолчанию для существующих и новых токенов.

Нажмите Save, чтобы применить список. Сохранение будет отклонено, если список содержит более 50 записей или запись, которая не является действительным адресом или диапазоном CIDR.

Что происходит, когда запрос поступает с неразрешенного адреса

Pushwoosh проверяет разрешенные IP-адреса при каждом вызове API, сделанном с помощью токена, будь то вызов REST v1 (как описано в этой справке по API, например, Messages API), вызов Messaging API v2 или вызов Customer Journey API. Запрос с адреса, не входящего в список разрешенных для токена, отклоняется.

Формат ответа зависит от того, какие вызовы вы делаете:

• Отправка, отмена и удаление сообщений, такие как createMessage, специфичные для канала методы create*Message, cancelMessage и deleteMessage, возвращают HTTP 200 с "status_code": 403 в теле ответа, так же, как и при других сбоях авторизации.
• Другие вызовы REST v1, такие как API для приложений, тегов, геозон, сегментации (фильтров), кампаний, пресетов, тестовых устройств и статистики, возвращают реальный HTTP 403 с телом ошибки в формате JSON.
• Messaging API v2 и Customer Journey API возвращают HTTP 403 с ошибкой PermissionDenied.

Изменения в списке разрешенных адресов вступают в силу в течение 10 минут

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