Documentation

Access tokens

The access token, or OAuth token, is a special code that grants access to a specific user's data. You need to get a separate token for each Yandex.Direct user that you make API requests on behalf of.

The token must be specified in every API request. The Yandex.Direct server uses the token to determine which user the app is making a request for, and whether this user actually granted the app access to personal data in Yandex.Direct. The app can only perform those actions that are allowed for the user that the token was obtained for.

For more information, see the Yandex.OAuth guide.

App registration

An app only needs to be registered on the Yandex.OAuth service one time. To do this, log in on Yandex with the app developer's username. For more information, see the section Registration on the Yandex.OAuth service in App registration.

Getting a token

Getting a token manually

At the app debugging stage, you can get a so-called debugging token in the name of a test user. See the section Debugging token in the Yandex.OAuth guide.

Getting a token automatically

When you are ready to begin working with real user data, you need to implement a user-friendly way to get tokens in the application. To get a token, the application should redirect the user to a special Yandex.OAuth page for requesting access. The user logs in on Yandex (with the username for Yandex.Direct) and clicks the Allow button to grant the application access to personal data. Yandex.OAuth generates a token and transmits it to the application automatically.

Yandex.OAuth supports multiple ways to transmit the token that are suitable for different types of applications: desktop programs, mobile apps, web services, and others. The flow for getting a token is covered in detail in the OAuth guide.

See also: PHP example, Python example.

Attention! Regardless of whether the token is obtained manually or automatically, it allows you to manage the user's real advertising materials.
Which method should I choose for getting a token?

In some cases, you can use tokens that you obtain manually after you switch to working with real user data. For example:

  • If the application only has a small number of users, who are representatives of a single advertiser.

  • If the application doesn't interact with the user. For example, this is a script for automatically updating bids.

Tokens should be obtained automatically if the application is accessed by multiple advertisers or a large number of users with different access rights.

Using the token when calling methods

The token obtained for a user must be specified in the HTTP Authorization header for every request to the Yandex.Direct API on behalf of this user.

If an invalid token is specified, an error message is returned with the code 1002.

Discontinuation of a token

Situations that cause a token to become invalid and require getting a new token are listed in the section Revoking tokens in the Yandex.OAuth guide.

Tip. 

If you are using an application, we recommend that you register a special representative in Yandex.Direct and get a token for the representative. See the section Recommendations for registering representatives.