Как получить доступ к API Яндекс Форм
Возможность использовать API Яндекс Форм есть у пользователей Форм для бизнеса. Подробнее см. Возможности Форм для бизнеса.
Для доступа к API Яндекс Форм можно использовать один из способов авторизации:
-
По протоколу OAuth 2.0 — используется как в организации Яндекс 360 для бизнеса, так и в Yandex Cloud Organization. Подробнее см. Получить доступ к API по протоколу OAuth 2.0.
-
С помощью IAM-токена — используется только в организации Yandex Cloud. Подробнее см. Получить доступ к API по IAM-токену.
При авторизации в API Яндекс Форм нельзя использовать сервисный аккаунт Yandex Cloud, отправляйте запросы только с аккаунта пользователя.
В запросах указывайте заголовки:
-
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. Полученный токен используйте в заголовке Authorization в запросах к API Яндекс Форм.
Токен предоставляет те же права, которые есть у аккаунта пользователя в Формах. Например, если у пользователя нет прав на получение ответов формы, соответствующие запросы к API будут недоступны.
Чтобы получить токен:
-
Перейдите по ссылке https://oauth.yandex.ru/.
-
На странице Ваши приложения нажмите Создать.
-
В открывшемся окне выберите вариант Для доступа к API или отладки и нажмите Перейти к созданию.
-
Укажите название приложение и почту для связи.
-
Добавьте разрешения для доступа к данным пользователя. Чтобы выбрать разрешение, начните вводить его название в поле Название доступа:
- Изменение настроек форм (forms:write) — все операции с данными: создание, удаление, редактирование.
- Просмотр настроек форм (forms:read) — только чтение данных.
-
Нажмите Создать приложение.
-
В личном кабинете Яндекс OAuth выберите созданное ранее приложение и скопируйте его идентификатор из поля ClientID.
-
Затем сформируйте ссылку для запроса токена:
https://oauth.yandex.ru/authorize?response_type=token&client_id=<идентификатор_приложения> -
Войдите в аккаунт, от имени которого вы будете работать с API, и перейдите по сформированной ссылке.
На странице появится последовательность символов — это 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.