Yandex OAuth implementation

Yandex services authorize applications via tokens. Each token is an alphanumeric sequence encoding the following information:

  • The ID of the account that can be accessed.

  • The ID of the application that was granted access.

  • A set of permissions (actions allowed for the application).

The general principles of using Yandex OAuth tokens are explained below.

Authorization flow

Applications use the following flow for requesting tokens:

  1. The application directs the user to the OAuth server. On the page that opens, the user can grant the application access to the requested account data. The application can request:
    • All types of access that were specified during application registration. In this case, the user must either grant or refuse all the requested access permissions at once.
    • Just specific access permissions that are needed right now, from the list of permissions that were specified during application registration. In this case, the user also must either grant or refuse all the requested access permissions at once.
    • The necessary access permissions from the list of permissions that were specified during application registration, along with optional permissions from the list that aren't necessary at the moment. An example of an optional permission is access to the profile picture. In this case, the user can grant all the necessary requested permissions at once, and choose which of the requested optional permissions to grant.
  2. The user grants access to personal data, and the OAuth server redirects the user to the address indicated by the developer.

    The token that is issued (or the code for obtaining it) is embedded in the redirect URL. If the user refused access or an error occurred, an error message is appended to the redirect URL.

  3. The application includes the received token in a request to a Yandex service that supports OAuth.

The received token can be stored in the application and used for requests until it expires.

Token lifespan

The token lifespan is how long the token can be used for authorization. The maximum lifespan depends on the permissions selected during application registration:

Perpetual token

Never expires and can only be revoked by the user.

During application registration, the lifespan is displayed as "indefinite".

Renewable token

Expires after several months, but is renewed each time this token is used for authorization.

The minimum lifespan is displayed during application registration, such as “at least 1 year”.

Limited token

Expires after the duration specified for the respective access permissions.

If multiple permissions were selected during application registration, the shortest time limit is applied to the token. For example, permissions to access Yandex.Metrica are set to 1 year, while permissions for using Yandex.Post Office are set to 180 days. This means that a token with permissions for both Yandex.Metrica and Yandex.Post Office will be valid for no longer than 180 days.

Revoking a token

Users can revoke any OAuth tokens that have been issued for their accounts:

  • To revoke all tokens that were ever issued for an account, the user can change the password or log out of all computers.
  • To revoke tokens that were issued to a specific application, the user can deny access for this application on the applications page.

An application can revoke its own token if it was issued for a specific device.

All situations for revoking a token are listed on the page Revoking tokens.

User interface

The page where the user can grant the application access (the first step in authorization) contains the application name and a list of requested permissions:

When the user clicks one of the buttons, the OAuth server redirects the user to the address specified as the Callback URL .