Как получить доступ к API Яндекс Форм

При работе с API Яндекс Форм запросы выполняются от имени пользователя. Чтобы выполнять те или иные действия через API, пользователь, от имени которого выполняется запрос, должен иметь соответствующие права в Формах. Например, если у пользователя нет прав на получение ответов формы, соответствующие запросы к 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-токена.

• Идентификатор организации:

  • X-Org-Id — для организации Яндекс 360 для бизнеса.
  • X-Cloud-Org-Id — для организации Yandex Cloud Organization.

  Чтобы узнать идентификатор организации, в сервисе Яндекс Трекер откройте страницу Администрирование → Организации и скопируйте значение поля идентификатор.

Пример:

Host: api.forms.yandex.net
Authorization: OAuth y0__xAbc*********
X-Org-Id: 1234******

Получить доступ к API по протоколу OAuth 2.0

Чтобы получить токен:

1. Перейдите по ссылке https://oauth.yandex.ru.

2. На странице Ваши приложения нажмите  Создать.

3. В открывшемся окне выберите вариант Для доступа к API или отладки и нажмите Перейти к созданию.

4. Укажите название приложения и почту для связи.

5. Добавьте разрешения для доступа к данным пользователя. Чтобы выбрать разрешение, начните вводить его название в поле Название доступа:

   • Изменение настроек форм (forms:write) — все операции с данными: создание, удаление, редактирование.
   • Просмотр настроек форм (forms:read) — только чтение данных.

6. Нажмите Создать приложение.

7. В личном кабинете Яндекс OAuth выберите созданное ранее приложение и скопируйте его идентификатор из поля ClientID.

8. Сформируйте ссылку для запроса токена:

   https://oauth.yandex.ru/authorize?response_type=token&client_id=<идентификатор_приложения>
   

9. Войдите в аккаунт, от имени которого вы будете работать с API, и перейдите по сформированной ссылке.

   На странице появится последовательность символов — это OAuth-токен. Скопируйте его и сохраните.

Инструкции по настройке приложения в Справке Яндекс ID:

• Как создать OAuth-приложение для доступа к API.
• Как получить токен.

Чтобы проверить наличие доступа к API, выполните какой-либо запрос. Если доступ не был получен, запрос вернет ответ с кодом 401 Unauthorized.

Например, выполнить запрос информации о текущем пользователе с помощью curl:

curl -X GET 'https://api.forms.yandex.net/v1/users/me/' \
     -H 'Authorization: OAuth y0__xAbc******' \
     -H 'X-Org-Id: 1234******'

curl -X GET "https://api.forms.yandex.net/v1/users/me/" ^
     -H "Authorization: OAuth y0__xAbc******" ^
     -H "X-Org-Id: 1234******"

Получить доступ к API по IAM-токену

Если вы используете Формы в составе организации Yandex Cloud, для авторизации в API можно использовать IAM-токен.

IAM-токен — уникальная последовательность символов, которая выдается пользователю после прохождения аутентификации. С помощью этого токена пользователь авторизуется в API Яндекс Форм и выполняет операции с ресурсами. Подробнее об этом способе аутентификации читайте в документации сервиса идентификации и контроля доступа.

• Как получить IAM-токен для аккаунта на Яндексе

• Как получить IAM-токен для федеративного аккаунта