API access

When working with Yandex Tracker API, requests are executed on behalf of a Tracker user. To perform certain actions via the API, the user on whose behalf the request is made must have the appropriate permissions in Tracker. For example, if a user doesn't have permission to change queue settings, the corresponding API requests will be unavailable. For more information about user permissions, see Roles and permissions.

To access Yandex Tracker API, you can use one of the following authentication methods:

  • OAuth 2.0 protocol. Used in both Yandex 360 organizations and Yandex Cloud organizations. In this case, specify the following header in requests to Tracker API:

    Authorization: OAuth <OAuth-token>

    For more information, see Get API access via OAuth 2.0 protocol.

  • Using an IAM token. Available only in Yandex Cloud organizations, including when using service accounts. In this case, specify the following header in requests to Tracker API:

    Authorization: Bearer <IAM-token>

    For more information, see Get API access via IAM token.

In addition to the token, you need to specify your organization ID in the request headers. The header format is described in Headers.

If you use the Python client to call the API, specify the authorization data when initializing the client: How to use the Python client.

Get API access via OAuth 2.0 protocol

If you use a federated or service account, authenticate using an IAM token.

To get a token:

  1. Go to https://oauth.yandex.com/.

  2. On the Your applications page, click Create.

  3. In the window that opens, select the For API access or debugging option and click Proceed to creation.

  4. Specify the application name and contact email.

  5. Add permissions to access user data. To select a permission, start typing its name in the Access name field:

    • Write to tracker (tracker:write) — all data operations: create, delete, edit.
    • Read from tracker (tracker:read) — read-only access to data.

  6. Click Create application.

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

  8. Generate the token request link:

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

  9. Log in to the account on whose behalf you will work with the API and go to the generated link.

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

To check if you have access to the API, execute the request for information about the current user. If access was not obtained, the request will return a response with code 401 Unauthorized.

Example request for information about the current user using curl:

curl -X GET 'https://api.tracker.yandex.net/v3/myself' \
     -H 'Authorization: OAuth y0__xAbc******' \
     -H 'X-Org-ID: 1234******'

curl -X GET "https://api.tracker.yandex.net/v3/myself" ^
     -H "Authorization: OAuth y0__xAbc******" ^
     -H "X-Org-ID: 1234******"

Get API access via IAM token

If you use Tracker as part of a Yandex Cloud organization, you can use an IAM token for API authorization.

An IAM token is a unique sequence of characters issued to a user after authentication. Using this token, the user authorizes in Yandex Tracker API and performs operations with resources.

To send requests to the Tracker API on behalf of a service account, first contact support specifying the cloud organization ID and service account ID. Otherwise, API requests will fail with error code 401 Unauthorized.

For more information about this authentication method, see the Identity and Access Management service documentation.

An IAM token is valid for no more than 12 hour and is limited by the cookie lifetime of the federation. After the token expires, an error with code 401 Unauthorized will be returned.

How to use the Python client

When developing applications in Python, you can use the yandex_tracker_client package — a client that simplifies working with Tracker API.

To start using the client:

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

  2. Run the following command in your OS command line:

    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:

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

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

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

The client uses the same data format as Yandex Tracker API.

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

Previous
API reference
Next
Common request format