Lesson 2. API access: how to register an app in Yandex OAuth

In this lesson, you will learn:

  1. What is OAuth authorization and OAuth token?
  2. How to register an app in Yandex OAuth
  3. What's next
  4. Useful links
  5. Questions

In this lesson, you will learn about the first step of getting access to Yandex Direct API for your app: registering your app in Yandex OAuth. The second step, requesting access, is covered in the next lesson.

In the previous lesson, you created your app developer account in Yandex Direct. Now you need to register your app with Yandex OAuth (you can do this even before creating your app).

What is OAuth authorization and OAuth token?

OAuth authorization is a mechanism that allows an app to handle the user data on their behalf without submitting the account password.

The authorization process uses OAuth tokens which are strings containing encrypted data:

  • user ID
  • ID of the app allowed to access user data in the service
  • set of permissions, i.e., actions permitted to the app.

To access Yandex Direct API your app must be registered with Yandex OAuth. After that, the user can allow the app to access their ads, and the app can get an OAuth token. The token must be specified in every API request: this way Yandex Direct can recognize the account the app is accessing and can check permissions for the actions.

  • Each token is unique, as it is issued for an “app + user” pair. You can not get two identical tokens or get more than one token for the same app-user pair.
  • If an app fails to pass the token in the API request, the server won't allow the app to get or change any data.

How to register an app in Yandex OAuth

Log in to Yandex with your developer username. In Yandex OAuth, open the New client page and fill out the main fields. You can modify any field anytime later.

  • App name — name to be visible to all users of the app.
  • Platforms — select the Web services checkbox and click the Set URL for development link, to manually get tokens during app development and debugging. In a next lesson, you will learn how to get tokens.

  • Accesses — in the Yandex Direct (direct) section, select checkbox Access to Yandex Direct API, to get access to ad management. The set of app accesses is also visible to all its potential users.
Note. If you want the app to access data of other Yandex services, for example, Yandex Metrica, you can also select relevant accesses. In this course, we focus on access to Yandex Direct data only.

After filling in the fields, click Create app. You will see the ID and password assigned to the app, in the page. You will need the app ID to fill out the API access request form and to obtain the token. You can look up the ID and other parameters in the Yandex OAuth web interface anytime you need them.

Attention. Only the developer has to register the app with Yandex OAuth. Users of your app do not need to do this, even if each user is working with their own instance (copy) of the app.

What's next

So, you took your first step in getting access to Yandex Direct API: registered your app in Yandex OAuth. In the next lesson, you will learn how to request the API access, and then how to get an OAuth token.


  1. How does Yandex Direct know which user account the app is using to access the API?
  2. Why do you need to register your app in the Yandex OAuth service?
    Incomplete answer.
    Incomplete answer.
  3. How does Yandex Direct API server respond if the OAuth token is missing in the request?