Доступ к API
Возможность использовать API Яндекс Форм есть у пользователей Форм для бизнеса. Подробнее см. Формы для бизнеса.
Для доступа к API Яндекс Форм можно использовать один из способов авторизации:
-
По протоколу OAuth 2.0 — используется как в организации Яндекс 360 для бизнеса, так и в Yandex Cloud Organization. Подробнее см. Получить доступ к API по протоколу OAuth 2.0.
-
С помощью IAM-токена — используется только в организации Yandex Cloud. Подробнее см. Получить доступ к API по IAM-токену.
В запросах указывайте заголовки:
-
Host: api.forms.yandex.net
-
Authorization: OAuth <OAuth-токен>
— при доступе по протоколу OAuth 2.0.Authorization: Bearer <IAM-токен>
— при доступе с помощью IAM-токена.Например:
Authorization: Bearer t1.ab123cd45*****************
.
Примечание
Передавать идентификатор организации в запросе не требуется, так как сервис Формы автоматически определяет организацию по коду формы и проверяет, что пользователь, выполняющий запрос, состоит в этой организации.
Получить доступ к API по протоколу OAuth 2.0
Для доступа к API Яндекс Форм требуется получить токен в сервисе OAuth. Токен предоставляет те же права, которые есть у аккаунта пользователя в Формах. Например, если у пользователя нет прав на получение ответов формы, соответствующие запросы к API будут недоступны.
Полученный токен используйте в заголовке Authorization
в запросах к API Яндекс Форм.
С базовыми принципами OAuth, а также с особенностями реализации протокола в Яндексе вы можете ознакомиться в документации сервиса OAuth для Яндекс ID.
Настроить выдачу токенов для пользователей
Допустим, вы хотите интегрировать ваше приложение или систему с Формами. Например, чтобы система могла получить ответы из формы с помощью API от имени пользователей вашей организации. Тогда для каждого пользователя системы нужно получать токен для доступа к API Яндекс Форм.
Чтобы настроить выдачу токенов для пользователей:
-
Перейдите по ссылке https://oauth.yandex.ru/client/new/ и зарегистрируйте приложение в сервисе OAuth: см. раздел Регистрация приложения в Справке Яндекс ID.
-
В разделе Доступ к данным добавьте разрешения для работы с API Яндекс Форм. Чтобы выбрать разрешение, начните вводить его название в поле Название доступа:
-
Запись настроек форм (forms:write) — все операции с данными: создание, удаление, редактирование.
-
Просмотр настроек форм (forms:read) — только чтение данных.
Скриншот
-
-
Выберите способ получения OAuth-токена и настройте его: см. раздел Получение OAuth-токена в Справке Яндекс ID.
Получить OAuth-токен
Если вам нужен доступ к API Яндекс Форм для тестирования, отладки или автоматизации, получите отладочный OAuth-токен:
-
Перейдите по ссылке https://oauth.yandex.ru/client/new/.
-
В разделе Платформы приложения выберите Веб-сервисы.
-
Установите курсор в поле Redirect URI и в подсказке нажмите Подставить URL для отладки. В поле будет подставлено значение
https://oauth.yandex.ru/verification_code
. -
В разделе Доступ к данным добавьте разрешения Запись настроек форм (forms:write) и Просмотр настроек форм (forms:read)
-
Чтобы получить отладочный токен:
-
В личном кабинете Яндекс OAuth выберите созданное ранее приложение и скопируйте его идентификатор из поля ClientID.
-
Затем сформируйте ссылку для запроса токена:
https://oauth.yandex.ru/authorize?response_type=token&client_id=<идентификатор_приложения>
- Перейдите по ссылке и скопируйте OAuth-токен. Подробнее читайте в Справке Яндекс ID.
-
Чтобы проверить наличие доступа к API, выполните какой-либо запрос. Если доступ не был получен, запрос вернет ответ с кодом 401 Unauthorized
.
Например, выполнить запрос информации о текущем пользователе с помощью curl:
curl -X GET 'https://api.forms.yandex.net/v1/users/me/' \
-H 'Authorization: OAuth ABC-def12GH_******'
curl -X GET "https://api.forms.yandex.net/v1/users/me/" ^
-H "Authorization: OAuth ABC-def12GH_******"
Получить доступ к API по IAM-токену
Если вы используете Формы в составе организации Yandex Cloud, для авторизации в API можно использовать IAM-токен.
IAM-токен — уникальная последовательность символов, которая выдается пользователю после прохождения аутентификации. С помощью этого токена пользователь авторизуется в API Яндекс Форм и выполняет операции с ресурсами. Подробнее об этом способе аутентификации читайте в документации сервиса идентификации и контроля доступа.
Примечание
IAM-токен действует не больше 12 часов и ограничен временем жизни cookie у федерации. После истечения срока жизни токена вернется ошибка с кодом 401 Unauthorized
.