Response format and content

The content of the response depends on the application permissions that were selected during registration on Yandex.OAuth. If multiple permissions are selected, the response is made up of the elements pertaining to each of these permissions.

Below you can find examples of responses for OAuth tokens with various permissions.

The response body is in JSON format by default. To get a response in XML format, include the format parameter in the request with the value "xml". The structure of elements is the same for both JSON and XML, with the exception that in XML format data is inside the <user> root tag.

  1. No permissions from the Yandex.Passport API section
  2. Access to email address
  3. Access to profile picture
  4. Access to date of birth
  5. Access to username, full name, and gender
  6. Sample response

No permissions from the Yandex.Passport API section

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

{
  "login": "vasya",
  "id": "1000034426",
  "openid_identities": [
    "http://openid.yandex.ru/vasya/",
    "http://vasya.ya.ru/"
  ]
}

Response element:

login

The Yandex username.

openid_identities

A list of all the OpenID identities that the user could have obtained from Yandex.

This list is used when migrating from Yandex OpenID to the Yandex.Passport API.

id

Unique Yandex user ID.

Access to email address

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

{
  "login": "vasya",
  "old_social_login": "uid-mmzxrnry",
  "default_email": "test@yandex.ru",
  "id": "1000034426",
  "emails": [
    "test@yandex.ru",
    "other-test@yandex.ru"
  ],
  "openid_identities": [
    "http://openid.yandex.ru/vasya/",
    "http://vasya.ya.ru/"
  ]
}

Response elements:

login

The Yandex username.

openid_identities

A list of all the OpenID identities that the user could have obtained from Yandex.

This list is used when migrating from Yandex OpenID to the Yandex.Passport API.

emails

Array of the user's email addresses.

This currently includes only one address, which is the default email address.

default_email

The default email address for contacting the user.

id

Unique Yandex user ID.

Access to profile picture

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

{
  "login": "vasya",
  "old_social_login": "uid-mmzxrnry",
  "id": "1000034426",
  "is_avatar_empty": false,
  "default_avatar_id": "131652443",
  "openid_identities": [
    "http://openid.yandex.ru/vasya/",
    "http://vasya.ya.ru/"
  ]
}

Response elements:

login

The Yandex username.

openid_identities

A list of all the OpenID identities that the user could have obtained from Yandex.

This list is used when migrating from Yandex OpenID to the Yandex.Passport API.

id

Unique Yandex user ID.

is_avatar_empty

Whether the default_avatar_id field is set to the placeholder ID (the generic picture that is set automatically during Yandex registration).

default_avatar_id

ID of the Yandex user's picture.

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 in the desired size, Yandex.Passport tries to find the face in the picture and crop the image to this 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.

Access to date of birth

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

{
  "login": "vasya",
  "old_social_login": "uid-mmzxrnry",
  "birthday": "1987-03-12",
  "id": "1000034426",
  "openid_identities": [
    "http://openid.yandex.ru/vasya/",
    "http://vasya.ya.ru/"
  ]  
}

Response elements:

login

The Yandex username.

openid_identities

A list of all the OpenID identities that the user could have obtained from Yandex.

This list is used when migrating from Yandex OpenID to the Yandex.Passport API.

birthday

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

Unknown parts 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 key "birthday": null is returned.
  • In an XML document, an empty <birthday/> tag is returned.
id

Unique Yandex user ID.

Access to username, full name, and gender

For a request with an OAuth token that has the Access to username, first name and surname, gender permission, the API returns the following response:

{
  "first_name": "\u0412\u0430\u0441\u044F",
  "last_name": "\u041F\u0443\u043F\u043A\u0438\u043D",
  "display_name": "Vasya",
  "real_name": "\u0412\u0430\u0441\u044F \u041F\u0443\u043F\u043A\u0438\u043D"
  "openid_identities": [
    "http://openid.yandex.ru/vasya/",
    "http://vasya.ya.ru/"
  ],
  "login": "vasya",
  "old_social_login": "uid-mmzxrnry",
  "sex": "male",
  "id": "1000034426"
}

Response elements:

first_name
The first name that the user entered in Yandex.Passport.
last_name
The last name that the user entered in Yandex.Passport.
display_name
The name that is displayed for this account in the Yandex interface.
real_name

The first and last name that the user specified in Yandex.Passport.

In JSON format, non-Latin characters in names are given in Unicode.

login

The Yandex username.

openid_identities

A list of all the OpenID identities that the user could have obtained from Yandex.

This list is used when migrating from Yandex OpenID to the Yandex.Passport API.

sex

The 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.
id

Unique Yandex user ID.

Sample response

The examples below show responses for an OAuth token that grants all the Yandex.Passport API permissions:

{
  "first_name": "\u0412\u0430\u0441\u044F",
  "last_name": "\u041F\u0443\u043F\u043A\u0438\u043D",
  "display_name": "Vasya",
  "emails": [
    "test@yandex.ru",
    "other-test@yandex.ru"
  ],
  "default_email": "test@yandex.ru",
  "real_name": "\u0412\u0430\u0441\u044F \u041F\u0443\u043F\u043A\u0438\u043D",
  "is_avatar_empty": false,
  "birthday": "1987-03-12",
  "default_avatar_id": "131652443",
  "openid_identities": [
    "http://openid.yandex.ru/vasya/",
    "http://vasya.ya.ru/"
  ],
  "login": "vasya",
  "old_social_login": "uid-mmzxrnry",
  "sex": "male",
  "id": "1000034426"
}