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.

Get 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 access request page, Yandex OAuth. 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: web services, desktop programs, mobile apps, 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 Recommendations for registering representatives.