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.



Attention.
  • 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.

  • Service name: Name to be displayed to all users of your service. You can also attach your service icon.
  • Platforms: Select the Web services checkbox. In the Redirect URI line, specify the URL to redirect the user to once they allow or deny the app access.
  • Data access: Specify Access to Yandex Direct API (direct:api) to get access to ad management. You can enter part of the name and then choose the appropriate one from the list.
Note. If you want the app to access data from other Yandex services, such as Yandex Metrica, you can also select relevant access permissions. In this course, we will focus on accessing Yandex Direct data only.
  • Email address: Specify your personal or corporate email address.

After filling in the fields, click Create app. The page will show the ID assigned to the app and the secret that the access token will be signed with. 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: you 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.

Questions

  1. How does Yandex Direct know which user account the app is using to access the API?
    False.
    False.
    True.
    False.
  2. Why do I need to register my app in Yandex OAuth?
    Incomplete answer.
    The answer is incomplete.
    True.
    False.
    False.
  3. How does the Yandex Direct API server respond if the OAuth token is missing in the request?
    False.
    True.
    False.