API access
To access the Yandex Wiki 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 Get access to the API using the OAuth protocol.
-
IAM token. Can only be used in Yandex Cloud organizations. For more information, see Access the API with an IAM token.
In Yandex Wiki API requests, specify the following headers:
-
Host: api.wiki.yandex.net
-
Authorization header:
-
Authorization: OAuth <OAuth_token>
— when using the OAuth 2.0 protocol. -
Authorization: Bearer <IAM_token>
— when using an IAM token.
-
-
Organization ID:
X-Org-Id
— for Yandex 360 for Business organizations.X-Cloud-Org-Id
— for Yandex Cloud Organization organizations.
Tip
To find your organization ID, open Yandex Tracker, go to Admin settings → Organizations, and copy the ID field value.
Example:
Host: api.wiki.yandex.net Authorization: Bearer t1.ab123cd45***************** X-Org-Id: bpfv7***************
Get access to the API using the OAuth protocol
To access Yandex Wiki API, you need to obtain an OAuth token. This token grants permissions that mirror those of the user account in Wiki. For example, if the user doesn't have permission to edit a page, they won't be able to make the corresponding API requests.
Use the obtained token in the Authorization
header when making requests to Yandex Wiki API.
For information about basic OAuth concepts and the Yandex implementation of the protocol, see the OAuth for Yandex ID documentation.
Setting up token issuance for users
Suppose you want to integrate your app or system with Wiki. For example, you may need your system to add rows to tables via the API on behalf of your organization's users. In this case, each user must be issued a token to access Yandex Wiki API.
To set up token issuance for users:
-
Follow the link https://oauth.yandex.ru/client/new/ or register your app in the OAuth service. For instructions, see the Register your app section in Yandex ID Help.
-
To select a permission, start typing its name in the Access name field:
-
Write to Wiki (wiki:write): Allow all operations with data: creating, deleting, and editing.
-
Read from Wiki (wiki:read): Allow read-only access to data.
-
-
Select and configure a method for obtaining an OAuth token. See the Get an OAuth token section in Yandex ID Help.
Get an OAuth token
If you need access to the Yandex Wiki API for testing, debugging, or automation purposes, obtain a debug OAuth token:
-
Follow this link: https://oauth.yandex.ru/client/new/.
-
Under Platforms, select Web services.
-
Hover over the Redirect URI field and click Enter URL for debugging in the tooltip. This will set the field value to
https://oauth.yandex.ru/verification_code
. -
To select a permission, start typing its name in the Access name field:
-
Write to Wiki (wiki:write): Allow all operations with data: creating, deleting, and editing.
-
Read from Wiki (wiki:read): Allow read-only access to data.
-
-
To get a debug token:
-
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>
- Follow the link and copy the OAuth token. For more information, see 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, here's how to request information about the mypage
page using curl:
curl -X GET 'https://api.wiki.yandex.net/v1/pages?slug=mypage' \
-H 'Authorization: OAuth ABC-def12GH_******' \
-H 'X-Org-Id: bpfv7***************'
curl -X GET "https://api.wiki.yandex.net/v1/pages?slug=mypage" ^
-H "Authorization: OAuth ABC-def12GH_******" ^
-H "X-Org-Id: bpfv7***************"
Access the API with an IAM token
If you're using Wiki 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 Wiki API and access resources. Read more about this authentication method in the documentation of the identification and access control service.
Note
The IAM token is valid for no more than 12 часов and is limited by the cookie lifetime for the federation. When the token expires, the 401 Unauthorized
error is returned.