API access

When using the Yandex Tracker API, requests are executed on behalf of a Yandex Tracker user. To run certain actions over the API, the user on whose behalf the request is executed must have relevant rights in Yandex Tracker. To learn more about user access rights, see Roles and access rights in Yandex Tracker.

To access the Yandex Tracker API, you can use one of these authorization methods:

• Via OAuth 2.0. Available for Yandex 360 and Yandex Cloud organizations. In this case, specify the header in your requests to the Tracker API:

  Authorization: OAuth <OAuth_token>

  For more information, see Getting access to the API via OAuth 2.0.

• Using an IAM token. Only works with Yandex Cloud organizations, including those using service accounts. In this case, specify the header in your requests to the Tracker API:

  Authorization: Bearer <IAM_token>

  For more information, see Access the API with an IAM token.

For information about the header format, see Headers.

If you use a Python client to call the API, specify authorization details when initializing the client. For more information, see Python client.

Getting access to the API via OAuth 2.0

To access Yandex Tracker API, you need to obtain an OAuth token. Use the obtained token in the Authorization header when making requests to Yandex Tracker API.

This token grants the same permissions as the user account in Yandex Tracker. For example, if the user is not allowed to change queue settings, API requests to change queue settings will not be available using this token.

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. Specify the app name and a contact email.

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

   • Write in tracker (tracker:write): Users with this permission can create, delete, and edit data.
   • Read from tracker (tracker:read): Users with this permission can only read data.

6. Click Create app.

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

8. Next, 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 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:

• How to create an OAuth app for accessing the API.
• How to obtain a token.

To check if you have access to the API, request information about the current user. If no access permission is granted, you will get a response with the 401 Unauthorized code.

Sample curl request for retrieving information about the current user:

curl -X GET 'api.tracker.yandex.net/v3/myself' \
     -H 'Authorization: OAuth ABC-def12GH_******' \
     -H 'X-Cloud-Org-Id: abcd12******'

curl -X GET "api.tracker.yandex.net/v3/myself" ^
     -H "Authorization: OAuth ABC-def12GH_******" ^
     -H "X-Cloud-Org-Id: abcd12******"

Access the API with an IAM token

If you're using Tracker 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 Tracker API and access resources.

To make requests to the Yandex Tracker API on behalf of a service account, first contact support and provide the IDs of your Yandex Cloud organization and the service account. Otherwise, API requests will return the 401 Unauthorized error code.

Read more about this authentication method in the documentation of the identification and access control service.

• How to get an IAM token for a Yandex account
• How to get an IAM token for a service account
• How to get an IAM token for a federated account

Python client

When developing applications in Python, you can use the yandex_tracker_client package, a client that makes it easier to work with Tracker API.

To start using the client:

1. Download and install the latest Python version from https://www.python.org/downloads/.

2. From your OS command line, run:

   pip install yandex_tracker_client
   

3. Get an OAuth token or IAM token for authorization.

4. Find out your organization ID.

   To get the organization ID, go to Administration → Organizations and copy the value from the ID field.

5. Initialize the client in your program code:

   In your Yandex 360 for Business organization

   In your Yandex Cloud organization

   from yandex_tracker_client import TrackerClient
   client = TrackerClient(token='<OAuth_token>', org_id='<organization_ID>')
   

   Here, <OAuth_token> is your OAuth token and <organization_ID> is your organization ID.

   For authorization using an OAuth token:

   from yandex_tracker_client import TrackerClient
   client = TrackerClient(token='<OAuth_token>', cloud_org_id='<organization_ID>')
   

   For authorization using an IAM token:

   from yandex_tracker_client import TrackerClient
   client = TrackerClient(iam_token='<IAM_token>', cloud_org_id='<organization_ID>')
   

   Here, <OAuth_token> or <IAM_token> is your token and <organization_ID> is your organization ID.

In the client, use the same data format as in the Yandex Tracker API.

For more information about how the client works and its terms of use, see its page on GitHub: https://github.com/yandex/yandex_tracker_client.