How to get access to the Yandex Forms API
The Yandex Forms API is available to Yandex Forms for Business users. For more information, see About Yandex Forms for Business.
To access the Yandex Forms API, you can use one of these authorization methods:
-
OAuth 2.0 protocol. Can be used in both Yandex 360 for Business and Yandex Cloud Organization organizations. For more information, see Getting access to the API via OAuth 2.0.
-
IAM token. Can only be used in Yandex Cloud organizations. For more information, see Access the API with an IAM token.
You can't use a Yandex Cloud service account for authorization in the Yandex Forms API. Send requests only from a user account.
In requests, specify these headers:
-
Host: api.forms.yandex.net -
Authorization: OAuth <OAuth_token>: If OAuth 2.0 is used.Authorization: Bearer <IAM_token>— when using an IAM token.For example:
Authorization: Bearer t1.ab123cd45*****************.
You don't need to transmit the organization ID in the request: Forms automatically detects the organization based on the form code and verifies that the user making the request is a member of that organization.
Getting access to the API via OAuth 2.0
To access Yandex Forms API, you need to obtain an OAuth token. Use the obtained token in the Authorization header when making requests to Yandex Forms API.
This token grants the same permissions that the user account has in Yandex Forms. For example, if the user doesn't have permissions to receive form answers, the user can't make API requests to retrieve them with this token.
To get a token:
-
Click the link https://oauth.yandex.ru/.
-
On the Your apps page, click Create.
-
In the window that opens, select For API access or debugging and click Create new token.
-
Enter the app name and contact email.
-
Add permissions for accessing user data. To select a permission, start typing its name in the Permission name field:
- Изменение настроек форм (forms:write) — all data operations: creation, deletion, editing.
- Просмотр настроек форм (forms:read) — read only.
-
Click Create app.
-
In your Yandex OAuth account, select the previously created application and copy its ID from the ClientID field.
-
Next, generate a link to request a token:
https://oauth.yandex.ru/authorize?response_type=token&client_id=<application_ID> -
Log in to the account which you'll be using to access the API, then follow the generated link.
You'll see a sequence of characters appear on the page — that's your OAuth token. Copy and save it.
See how to set up your app in Yandex ID Help:
To check if you have access to the API, send any request. If no access permission is granted, you will get a response with the 401 Unauthorized code.
For example, to retrieve information about the current user with 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_******"
Access the API with an IAM token
If you're using Forms as part of a Yandex Cloud organization, you can authorize with the API using an IAM token.
An IAM token is a unique sequence of characters issued to a user after authentication. The user needs this token to authorize with the Yandex Forms API and access resources. Read more about this authentication method in the documentation of the identification and access control service.
The IAM token is valid for no more than 12 hours and is limited by the cookie lifetime for the federation. When the token expires, the 401 Unauthorized error is returned.