Exchange the token for user information

When you request user information, API Yandex ID returns all the data that the OAuth token specified in the request grants access to.

The contents of the response depend on the app permissions that were selected during registration in Yandex OAuth. If multiple permissions are selected, the response is made up of the elements pertaining to each of these permissions.

Note

To send a request to API Yandex ID, you can use an OAuth token with permissions to access any of the Yandex services. However, only tokens with permissions from the API Yandex ID section set during app registration provide extended access to user data.

Request format

A request for information about a Yandex user is formed like this:

GET https://login.yandex.ru/info?
[& format=json | xml | jwt]
[& jwt_secret=<secret key>]

Authorization: OAuth <OAuth token>

GET https://login.yandex.ru/info?
 & oauth_token=<OAuth token>
[& format=json | xml | jwt]
[& jwt_secret=<secret key>]

Alert

When this method is used, the OAuth token is passed in a parameter of a GET request and may remain publicly available in the browser history or in access logs of any intermediate host. An attacker may exploit such a token.

Request parameters

Parameter

Value

Description

oauth_token

The OAuth token allowing to access the user's account data via API Yandex ID. The contents of the response depend on the permissions that are granted by the OAuth token specified in the request.

The OAuth token must be included in the request in one of these two ways:

  • In the HTTP Authorization header each time API Yandex ID is called, with the token type preceding its value (recommended method):

    Authorization: OAuth <OAuth-token>

  • In the value of the oauth_token parameter (unsafe method):

    oauth_token=<OAuth token>

format

xml | json | jwt

The format in which data should be returned. Possible values:

  • json — a JSON document. This value is used by default if the parameter is not specified in the request.
  • xml — an XML document.
  • jwt — a JSON Web Token.

jwt_secret

The secret to sign the JWT with. If this parameter isn't passed, the client_secret of the OAuth app is used instead.
We recommend not to pass this parameter.

Response format

The response contains a set of standard and additional fields depending on the app permissions.

The response body is in JSON format by default. To get a response in XML or JWT format, include the format parameter with the xml or jwt value in the request:

  • An XML response has the same structure as a JSON response. Data is wrapped in a root <user> tag.
  • A JWT response always includes a standard set of fields. Depending on the selected permissions, additional fields may also be returned.

Standard response parameters

The response to a request for user information contains the fields listed below:

Property

Description

login

Yandex username.

id

Unique Yandex user ID.

client_id

ID of the app for which the OAuth token passed in the request was issued. Can be found in the app properties. To open them, select the app name.

uid

"id" equivalent. This field is only available in JWT format.

psuid

Yandex ID of the logged in user. Generated by Yandex based on the client_id and user_id.

Additional response parameters

Additional response fields depend on the permissions selected when registering the app in Yandex OAuth and provided by the OAuth token:

If multiple permissions are selected, the response is made up of the elements pertaining to each of these permissions.

No permissions from the section API Yandex ID

A request to API Yandex ID can use an OAuth token that was issued for a different Yandex service. If the token is valid, the API returns the following response:

{
   "login": "ivan",
   "id": "1000034426",
   "client_id": "4760187d81bc4b7799476b42b5103713",
   "psuid": "1.AAceCw.tbHgw5DtJ9_zeqPrk-Ba2w.qPWSRC5v2t2IaksPJgnge"
}

<?xml version="1.0" encoding="utf-8"?>
<user>
  <login>ivan</login>
  <id>1000034426</id>
  <client_id>4760187d81bc4b7799476b42b5103713</client_id>
  <psuid>1.AAceCw.tbHgw5DtJ9_zeqPrk-Ba2w.qPWSRC5v2t2IaksPJgnge</psuid>
</user>

{
   "iat": 1620915565,
   "jti": "384b6169-b3f6-11eb-a7cd-0c42a10aa38c",
   "exp": 1652451414,
   "iss": "login.yandex.ru",
   "uid": 1000034426,
   "login": "ivan",
   "psuid": "1.AAceCw.tbHgw5DtJ9_zeqPrk-Ba2w.qPWSRC5v2t2IaksPJgnge"
}

The response contains a standard set of fields.

Access to the email address

For a request with an OAuth token that has the Email address permission, the API returns the following response:

{
   "login": "ivan",
   "old_social_login": "uid-mmzxrnry",
   "default_email": "test@yandex.ru",
   "id": "1000034426",
   "client_id": "4760187d81bc4b7799476b42b5103713",
   "emails": [
      "test@yandex.ru",
      "other-test@yandex.ru"
   ],
   "psuid": "1.AAceCw.tbHgw5DtJ9_zeqPrk-Ba2w.qPWSRC5v2t2IaksPJgnge"
}

<?xml version="1.0" encoding="utf-8"?>
<user>
  <login>ivan</login>
  <old_social_login>uid-mmzxrnry</old_social_login>
  <default_email>test@yandex.ru</default_email>
  <id>1000034426</id>
  <client_id>4760187d81bc4b7799476b42b5103713</client_id>
  <emails>
    <address>test@yandex.ru</address>
    <address>other-test@yandex.ru</address>
  </emails>
  <psuid>1.AAceCw.tbHgw5DtJ9_zeqPrk-Ba2w.qPWSRC5v2t2IaksPJgnge</psuid>
</user>

{
   "iat": 1620915565,
   "jti": "384b6169-b3f6-11eb-a7cd-0c42a10aa38c",
   "exp": 1652451414,
   "iss": "login.yandex.ru",
   "uid": 1000034426,
   "login": "ivan",
   "email": "test@yandex.ru",
   "psuid": "1.AAceCw.tbHgw5DtJ9_zeqPrk-Ba2w.qPWSRC5v2t2IaksPJgnge"
}

The response contains a standard set of fields and additional parameters:

Property

Description

emails

Array of the user's email addresses. This currently includes only one address, which is the default email address.

default_email

Default email address for contacting the user.

email

default_email equivalent. This field is only available in JWT format.

Access to the user avatar

For a request with an OAuth token that has the User avatar permission, the API returns the following response:

{
   "login": "ivan",
   "old_social_login": "uid-mmzxrnry",
   "id": "1000034426",
   "client_id": "4760187d81bc4b7799476b42b5103713",
   "is_avatar_empty": false,
   "default_avatar_id": "131652443",
   "psuid": "1.AAceCw.tbHgw5DtJ9_zeqPrk-Ba2w.qPWSRC5v2t2IaksPJgnge"
}

<?xml version="1.0" encoding="utf-8"?>
<user>
  <login>zamulla.aleksey</login>
  <old_social_login>uid-mmzxrnry</old_social_login>
  <id>31652443</id>
  <client_id>4760187d81bc4b7799476b42b5103713</client_id>
  <is_avatar_empty>False</is_avatar_empty>
  <default_avatar_id>31652443</default_avatar_id>
  <psuid>1.AAceCw.tbHgw5DtJ9_zeqPrk-Ba2w.qPWSRC5v2t2IaksPJgnge</psuid>
</user>

{
   "iat": 1620915565,
   "jti": "384b6169-b3f6-11eb-a7cd-0c42a10aa38c",
   "exp": 1652451414,
   "iss": "login.yandex.ru",
   "uid": 1000034426,
   "login": "ivan",
   "avatar_id": "131652443",
   "psuid": "1.AAceCw.tbHgw5DtJ9_zeqPrk-Ba2w.qPWSRC5v2t2IaksPJgnge"
}

The response contains a standard set of fields and additional parameters:

Property

Description

is_avatar_empty

Flag indicating whether the default_avatar_id field is set to the placeholder ID (the generic avatar that is added automatically when creating a Yandex account).

default_avatar_id

ID of the Yandex user's avatar.
To download the picture with the given ID, use a link in the following format:

https://avatars.yandex.net/get-yapic/<avatar ID>/<size>

If a picture with the passed ID doesn't exist, it links to the generic picture in the specified size.

Available sizes

To get an image of the desired size, Yandex tries to locate a face in the avatar and crops the image to that area.

Values that can be set in the picture URL:

  • islands-small — 28×28 pixels.
  • islands-34 — 34×34 pixels.
  • islands-middle — 42×42 pixels.
  • islands-50 — 50×50 pixels.
  • islands-retina-small — 56×56 pixels.
  • islands-68 — 68×68 pixels.
  • islands-75 — 75×75 pixels.
  • islands-retina-middle — 84×84 pixels.
  • islands-retina-50 — 100×100 pixels.
  • islands-200 — 200×200 pixels.

avatar_id

default_avatar_id equivalent. This field is only available in JWT format.

Access to the date of birth

For a request with an OAuth token that has the Date of birth permission, the API returns the following response:

{
   "login": "ivan",
   "old_social_login": "uid-mmzxrnry",
   "birthday": "1987-03-12",
   "id": "1000034426",
   "client_id": "4760187d81bc4b7799476b42b5103713",
   "psuid": "1.AAceCw.tbHgw5DtJ9_zeqPrk-Ba2w.qPWSRC5v2t2IaksPJgnge"
}

<?xml version="1.0" encoding="utf-8"?>
<user>
  <login>ivan</login>
  <old_social_login>uid-mmzxrnry</old_social_login>
  <birthday>1987-03-12</birthday>
  <id>1000034426</id>
  <client_id>4760187d81bc4b7799476b42b5103713</client_id>
  <psuid>1.AAceCw.tbHgw5DtJ9_zeqPrk-Ba2w.qPWSRC5v2t2IaksPJgnge</psuid>
</user>

{
   "iat": 1620915565,
   "jti": "384b6169-b3f6-11eb-a7cd-0c42a10aa38c",
   "exp": 1652451414,
   "iss": "login.yandex.ru",
   "uid": 1000034426,
   "login": "ivan",
   "birthday": "1987-03-12",
   "psuid": "1.AAceCw.tbHgw5DtJ9_zeqPrk-Ba2w.qPWSRC5v2t2IaksPJgnge"
}

The response contains a standard set of fields and an additional parameter:

Property

Description

birthday

User's date of birth, in the format YYYY-MM-DD.

Unknown parts of the date are filled in with zeros, for example: 0000-12-23.

If the user's date of birth is unknown:

  • In a JSON document, the key "birthday": null is returned.
  • In an XML document, an empty <birthday/> tag is returned.

Access to the username, first name, last name, and gender

For a request with an OAuth token that has the Username, first name, last name, and gender permission, the API returns the following response:

{
   "first_name": "Ivan",
   "last_name": "Ivanov",
   "display_name": "Ivan",
   "real_name": "Ivan Ivanov",
   "login": "ivan",
   "old_social_login": "uid-mmzxrnry",
   "sex": "male",
   "id": "1000034426",
   "client_id": "4760187d81bc4b7799476b42b5103713",
   "psuid": "1.AAceCw.tbHgw5DtJ9_zeqPrk-Ba2w.qPWSRC5v2t2IaksPJgnge"
}

<?xml version="1.0" encoding="utf-8"?>
<user>
  <first_name>Ivan</first_name>
  <last_name></last_name>
  <display_name>Ivan</display_name>
  <real_name>Ivan Ivanov</real_name>
  <login>ivan</login>
  <old_social_login>uid-mmzxrnry</old_social_login>
  <sex>male</sex>
  <id>1000034426</id>
  <client_id>4760187d81bc4b7799476b42b5103713</client_id>
  <psuid>1.AAceCw.tbHgw5DtJ9_zeqPrk-Ba2w.qPWSRC5v2t2IaksPJgnge</psuid>
</user>

{
   "iat": 1620915565,
   "jti": "384b6169-b3f6-11eb-a7cd-0c42a10aa38c",
   "exp": 1652451414,
   "iss": "login.yandex.ru",
   "login": "ivan",
   "uid": 1000034426,
   "display_name": "Ivan",
   "name": "Ivan Ivanov",
   "gender": "male",
   "psuid": "1.AAceCw.tbHgw5DtJ9_zeqPrk-Ba2w.qPWSRC5v2t2IaksPJgnge"
}

The response contains a standard set of fields and additional parameters:

Property

Description

first_name

First name that the user set in Yandex ID.

last_name

Last name that the user set in Yandex ID.

display_name

Name that's displayed for this account in the Yandex interface.

real_name

First and last name that the user set in Yandex ID.
In JSON format, non-Latin characters in names are given in Unicode.

sex

User's gender. Possible values:

  • male
  • female
  • Gender unknown:
    • In a JSON document, this is indicated by the key "sex": null.
    • In an XML document, this is indicated by an empty <sex/> tag.

gender

sex equivalent. This field is only available in JWT format.

Access to the phone number

For a request with an OAuth token that has the Phone number permission, the API returns the following response:

{
   "login": "ivan",
   "id": "1000034426",
   "client_id": "4760187d81bc4b7799476b42b5103713",
   "default_phone": {
      "id": 12345678,
      "number": "+79037659418"
   },
   "psuid": "1.AAceCw.tbHgw5DtJ9_zeqPrk-Ba2w.qPWSRC5v2t2IaksPJgnge"
}

<?xml version="1.0" encoding="utf-8"?>
<user>
  <login>ivan</login>
  <id>1000034426</id>
  <client_id>4760187d81bc4b7799476b42b5103713</id>
  <psuid>1.AAceCw.tbHgw5DtJ9_zeqPrk-Ba2w.qPWSRC5v2t2IaksPJgnge</psuid>
  <default_phone>
    <id>12345678</id>
    <number>+79037659418</number>
  </default_phone>
</user>

{
   "iat": 1620915565,
   "jti": "384b6169-b3f6-11eb-a7cd-0c42a10aa38c",
   "exp": 1652451414,
   "iss": "login.yandex.ru",
   "uid": 1000034426,
   "login": "ivan",
   "number": "+79037659418",
   "psuid": "1.AAceCw.tbHgw5DtJ9_zeqPrk-Ba2w.qPWSRC5v2t2IaksPJgnge"
}

The response contains a standard set of fields and additional parameters:

Property

Description

default_phone

Default phone number for contacting the user. This field contains the following parameters:

  • id — Phone number's ID.
  • number — User's phone number.

Example

If the app has an OAuth token that grants it all the API Yandex ID permissions, the response contains all the standard and additional parameters:

{
   "first_name": "Ivan",
   "last_name": "Ivanov",
   "display_name": "ivan",
   "emails": [
      "test@yandex.ru",
      "other-test@yandex.ru"
   ],
   "default_email": "test@yandex.ru",
   "default_phone": {
      "id": 12345678,
      "number": "+79037659418"
   },
   "real_name": "Ivan Ivanov",
   "is_avatar_empty": false,
   "birthday": "1987-03-12",
   "default_avatar_id": "131652443",
   "login": "ivan",
   "old_social_login": "uid-mmzxrnry",
   "sex": "male",
   "id": "1000034426",
   "client_id": "4760187d81bc4b7799476b42b5103713",
   "psuid": "1.AAceCw.tbHgw5DtJ9_zeqPrk-Ba2w.qPWSRC5v2t2IaksPJgnge"
}

<?xml version="1.0" encoding="utf-8"?>
<user>
   <first_name>Ivan</first_name>
   <last_name>Ivanov</last_name>
   <display_name>ivan</display_name>
   <emails>
      <address>test@yandex.ru</address>
      <address>other-test@yandex.ru</address>
   </emails>
   <default_email>test@yandex.ru</default_email>
   <default_phone>
      <id>12345678</id>
      <number>+79037659418</number>
   </default_phone>
   <real_name>Ivan Ivanov</real_name>
   <is_avatar_empty>False</is_avatar_empty>
   <birthday>1987-03-12</birthday>
   <default_avatar_id>131652443</default_avatar_id>
   <login>ivan</login>
   <old_social_login>uid-mmzxrnry</old_social_login>
   <sex>male</sex>
   <id>1000034426</id>
   <client_id>4760187d81bc4b7799476b42b5103713</client_id>
   <psuid>1.AAceCw.tbHgw5DtJ9_zeqPrk-Ba2w.qPWSRC5v2t2IaksPJgnge</psuid>
</user>

{
   "iat": 1620915565,
   "jti": "384b6169-b3f6-11eb-a7cd-0c42a10aa38c",
   "exp": 1652451414,
   "iss": "login.yandex.ru",
   "uid": 1000034426,
   "login": "ivan",
   "avatar_id": "131652443",
   "email": "test@yandex.ru",
   "number": "+79037659418",
   "display_name": "ivan",
   "name": "Ivan Ivanov",
   "gender": "male",
   "psuid": "1.AAceCw.tbHgw5DtJ9_zeqPrk-Ba2w.qPWSRC5v2t2IaksPJgnge"
}
Previous
Enter the code on the Yandex OAuth authorization page
Next
Debug token