Авторизация по oAuth

Используя открытую часть API, можно получить доступ только к некоторым полям публичных событий. Если для вашего приложения нужны сведения о билетах или о приватных событиях и черновиках, необходимо совершить авторизацию через OAuth2.

Схема работы с защищёнными данными организации выглядит следующим образом:

  1. Разработчик создаёт приложение в своей учётной записи на TimePad
  2. Разработчик или приложение генерирует ссылку для авторизации организатора
  3. Организатор переходит по этой ссылке и подтверждает выдачу доступа к защищённым данным
  4. Приложение получает токен для работы с защищённой частью API
  5. Приложение выполняет запросы к API, используя токен
Внимание! Страница добавления приложения пока доступна не всем. Если вы ее не видите, но хотите создавать приложения, напишите нам на api@timepad.ru.

Создание приложения

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

Создание приложения
Получение ClientId

Создания авторизующей ссылки

Ссылка авторизации приложения выглядит таким образом:

https://api.timepad.ru/oauth/authorize/?client_id={ClientId}&redirect_uri={ReturnUrl}&scope={ScopeList}&response_type=token

Где

  • ClientId - Полученный в настройках приложения идентификатор приложения
  • ReturnUrl - Ссылка, на которую будет возвращён пользователь после авторизации или неудачной попытки входа. Обязательно должна совпадать со ссылкой, указанной при создании приложения
  • ScopeList - Необходимые приложению права доступа через запятую. Бывают такие:
    • view_private_events - Доступ к непубличным событиям организатора
    • add_cash_payments - Возможность отмечать билеты как оплаченные наличными
    • view_visitors - Доступ к списку посетителей события
    • edit_visitors - Доступ к редактированию участников события
    • edit_events - Доступ к редактированию события
    • add_organizations - Доступ к добавлению организаций
    • add_events - Доступ к добавлению событий

Пример создания авторизационной ссылки на PHP:

<?
  $authScope  = [
      'view_private_events',
      'view_visitors'
  ];

  $authLink   = [
      'client_id'     => '29ad0941eaaf781ba34825ca9919f91cde647b9c',
      'redirect_uri'  => 'https://test-api.ru/auth',
      'scope'         => implode(',', $authScope),
      'response_type' => 'token'
  ];

  $url  = 'https://api.timepad.ru/oauth/authorize?' . http_build_query($authLink);
?>

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

Организатор, перейдя по авторизующей ссылке, увидит страницу выдачи приложению доступа. Здесь можно увидеть краткую информацию о приложении, а также выдать доступ к защищённым данным.

Страница выдачи доступа

Отказ

В случае если организатор нажал «Отказать», его перенаправляет на страницу:

https://test-api.ru/auth?error=access_denied&error_description=%D0%9F%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D1%8C+%D0%BE%D1%82%D0%BA%D0%BB%D0%BE%D0%BD%D0%B8%D0%BB+%D0%B7%D0%B0%D0%BF%D1%80%D0%BE%D1%81

Где https://test-api.ru/auth — это ссылка редиректа приложения, а в error и error_description — код отказа и его описание.

Авторизация

При нажатии на кнопку «Авторизовать» пользователя перенаправит на такую ссылку:

https://test-api.ru/auth#access_token=0d102d20fb8657dc8a23a864726c7bdd09a6ce59

Как видите, в ссылку добавлен параметр access_token, стоящий после символа решётки. В данном случае значение токена – 0d102d20fb8657dc8a23a864726c7bdd09a6ce59.

Использование Api с защищённым токеном

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

Для этого достаточно добавить в url GET-параметр token, например:

https://api.timepad.ru/v1/events.json?token=0d102d20fb8657dc8a23a864726c7bdd09a6ce59

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

Токен может оказаться недействительным (никогда не существовал, истёк срок действия, либо отозван). Например, при такой ссылке:

https://api.timepad.ru/v1/events.json?token=1234560fb8657dc8a23a864726c7bd123456789

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

Ошибка токена

Безопасная передача токена

Токен можно передавать не в GET-запросе, а в http-заголовке Authorization. Выглядит заголовок так:

    Authorization: Bearer 0d102d20fb8657dc8a23a864726c7bdd09a6ce59

Сделать в PHP это можно таким образом:

<?
  $access_key = '0d102d20fb8657dc8a23a864726c7bdd09a6ce59';
  $curl = curl_init('https://api.timepad.ru/v1/events.json');
  curl_setopt($curl, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $access_key] );
  curl_exec($curl);
?>