API access

When working with Yandex Wiki API, requests are made on behalf of a user. To perform actions through the API, the user on whose behalf the request is made must have the appropriate permissions in Wiki. For example, if the user does not have permission to edit a page, the corresponding API requests will be unavailable. For more information about user permissions, see Roles.

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 Getting access to the API using the OAuth protocol.

• IAM token — can only be used in Yandex Cloud organizations. For more information, see Getting access to the API with an IAM token.

Headers

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.

  To find your organization ID, open Yandex Tracker, go to Administration → Organizations, and copy the ID field value.

Example:

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

Getting access to the API using the OAuth protocol

To get a token:

1. Click the link https://oauth.yandex.com.

2. On the Your apps page, click Create.

3. In the window that opens, select For API access or debugging and click Create new token.

4. Enter the app name and contact email.

5. Add permissions for accessing user data. To select a permission, start typing its name in the Permission name field:

   • Write to Wiki (wiki:write) — все операции с данными: создание, удаление, редактирование.
   • Read from Wiki (wiki:read) — только чтение данных.

6. Click Create app.

7. In your Yandex OAuth account, select the previously created application and copy its ID from the ClientID field.

8. Generate a link to request a token:

   https://oauth.yandex.com/authorize?response_type=token&client_id=<application_ID>
   

9. Log in to the account you will use to access the API, then follow the generated link.

   A sequence of characters will appear on the page — that is your OAuth token. Copy and save it.

To check if you have access to the API, send any request. If access has not been granted, the request will return a 401 Unauthorized response.

For example, you can request information about the mypage page using curl:

curl -X GET 'https://api.wiki.yandex.net/v1/pages?slug=mypage' \
     -H 'Authorization: OAuth y0__xAbc******' \
     -H 'X-Org-Id: 1234******'

curl -X GET "https://api.wiki.yandex.net/v1/pages?slug=mypage" ^
     -H "Authorization: OAuth y0__xAbc******" ^
     -H "X-Org-Id: 1234******"

Getting access to the API with an IAM token

If you are 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 uses this token to authorize with the Yandex Wiki API and perform operations on resources. For more information about this authentication method, see the documentation of the identity and access management service.

• How to get an IAM token for a Yandex account

• How to get an IAM token for a federated account