Exchanging the token for information about the user

When you request information about a user, API Yandex ID returns all the data that the OAuth token specified in the request has access rights for.

The service's response content depends on the app rights selected when registering the app at Yandex OAuth. If multiple rights are selected, the response includes the elements unique for each right.

Note

To send a request to API Yandex ID, you may use an OAuth token with permissions to access any of the Yandex services. However, extended access to user data is only available if you have tokens with access rights from the API Yandex ID section configured when registering the app.

Request format

A request for information about a Yandex user has the following format:

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

In this method, the OAuth token is sent in the GET request parameter and can be saved openly in the browser history or in the access logs of any intermediate host. The saved OAuth token may be used by a hacker.

Request parameters

Parameter

Value

Description

oauth_token

An OAuth token that enables access of the user's account data via API Yandex ID. The content of the response depends on the rights granted by the OAuth token specified in the request.

The OAuth token must be specified in the request in one of the following ways:

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

    Authorization: OAuth <OAuth token>

  • In the oauth_token parameter value (insecure method):

    oauth_token=<OAuth token>

format

xml | json | jwt

Returned data format. Possible values:

  • json: JSON document. This value is used by default if the parameter isn't specified in the request.
  • xml: XML document.
  • jwt: JSON Web Token.

jwt_secret

The secret that will be used to sign JWT. If the parameter is not passed, the OAuth app's client_secret will be used instead.
We recommend that you do not pass this parameter.

Response format

In the response, the service returns a set of standard and additional fields depending on the app's access rights.

The default response body format is JSON. You can also get a response in XML or JWT format. To do this, specify the format parameter with the xml or jwt value in the request:

  • The XML format response has the same structure as JSON. Data is wrapped in the <user> root tag.
  • The response in JWT format always has a standard set of fields. Depending on the selected rights, special fields also return in addition to the standard fields.

Standard response parameters

The response to the user information request contains the set of fields listed below:

Property

Description

login

User's Yandex login.

id

Yandex user's unique ID.

client_id

The ID of the app the OAuth token in the request was issued for. Available in the app properties. To open properties, click the app name.

uid

Same as id. The field is only available in JWT format.

psuid

Authorized Yandex user ID. It is formed on the Yandex side based on the client_id and user_id pair.

Advanced response parameters

Additional response fields depend on the rights selected when registering the app at Yandex OAuth and granted by the OAuth token:

If multiple rights are selected, the response includes the elements unique for each right.

Missing rights from theAPI Yandex ID section

A request to API Yandex ID can use an OAuth token 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 the standard set of fields.

Access to email address

For a request with an OAuth token that has the Email address access right, 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 the standard set of fields as well as advanced parameters:

Property

Description

emails

An array of the user's email addresses. Currently only includes the default email address.

default_email

The default email address for contacting the user.

email

Same as default_email. The field is only available in JWT format.

uid

Same as id. The field is only available in JWT format.

Access to the user's profile picture

For a request with an OAuth token that has the User's profile picture access right, 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 the standard set of fields as well as advanced parameters:

Property

Description

is_avatar_empty

Indicates that the stub (profile picture that is automatically assigned when registering in Yandex) ID is specified in the default_avatar_id field.

default_avatar_id

ID of the Yandex user's profile picture.
The profile picture with this ID can be downloaded via a link that looks like this:

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

If the profile picture with the passed ID is missing, a stub of the specified size will be found by the link.

Available size

To get an image in the desired size, Yandex tries to find the face in the picture and crop the image to this area.

Values that can be set in the profile picture's 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

Same as default_avatar_id. The field is only available in JWT format.

uid

Same as id. The 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 access right, 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 the standard set of fields as well as advanced parameters:

Property

Description

birthday

The user's date of birth in YYYY-MM-DD format.

Unknown elements of the date are filled in with zeros, such as: 0000-12-23.

If the user's date of birth is unknown:

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

uid

Same as id. The field is only available in JWT format.

Access to login, first name, last name, and gender

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

{
   "first_name": "John",
   "last_name": "Doe",
   "display_name": "John",
   "real_name": "John Doe",
   "login": "john",
   "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>John</first_name>
  <last_name></last_name>
  <display_name>John</display_name>
  <real_name>John Doe</real_name>
  <login>john</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": "john",
   "uid": 1000034426,
   "display_name": "John",
   "name": "John Doe",
   "gender": "male",
   "psuid": "1.AAceCw.tbHgw5DtJ9_zeqPrk-Ba2w.qPWSRC5v2t2IaksPJgnge"
}

The response contains the standard set of fields as well as advanced parameters:

Property

Description

first_name

The first name that the user specified in Yandex ID.

last_name

The last name that the user specified in Yandex ID.

display_name

The name displayed for this account in the Yandex interface.

real_name

The first and last name that the user specified in Yandex ID.
In JSON format, non-Latin characters of the first and last names are presented in Unicode format.

sex

User's gender. Possible values:

  • Male.
  • Female.
  • Unknown gender:
    • In a JSON document, this is usually indicated by the "sex": null key.
    • In an XML document, this is indicated by an empty <sex/> tag.

uid

Same as id. The field is only available in JWT format.

gender

Same as sex. The field is only available in JWT format.

Access to the phone number

For a request with an OAuth token that has the Phone number access right, 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 the standard set of fields as well as advanced parameters:

Property

Description

default_phone

The default phone number for contacting the user. The API can exclude the user's phone number from the response at its discretion. The field contains the following parameters:

  • id: Phone number ID.
  • number: The user's phone number.

uid

Same as id. The field is only available in JWT format.

Example

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

{
   "first_name": "John",
   "last_name": "Doe",
   "display_name": "john",
   "emails": [
      "test@yandex.ru",
      "other-test@yandex.ru"
   ],
   "default_email": "test@yandex.ru",
   "default_phone": {
      "id": 12345678,
      "number": "+79037659418"
   },
   "real_name": "John DOe",
   "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>John</first_name>
   <last_name>Doe</last_name>
   <display_name>john</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>John Doe</real_name>
   <is_avatar_empty>False</is_avatar_empty>
   <birthday>1987-03-12</birthday>
   <default_avatar_id>131652443</default_avatar_id>
   <login>john</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": "john",
   "avatar_id": "131652443",
   "email": "test@yandex.ru",
   "number": "+79037659418",
   "display_name": "john",
   "name": "John Doe",
   "gender": "male",
   "psuid": "1.AAceCw.tbHgw5DtJ9_zeqPrk-Ba2w.qPWSRC5v2t2IaksPJgnge"
}
Previous
Step 2. Getting an OAuth token
Next
Personal account Yandex OAuth
In this article: