---
metadata:
  - name: generator
    content: Diplodoc Platform v5.44.0
alternate:
  - https://yandex.ru/dev/id/doc/en/user-information.md
  - https://yandex.ru/dev/id/doc/ru/user-information.md
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/dev/id/doc/en/llms.txt

# 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](https://yandex.ru/dev/id/doc/en/register-client.md) at Yandex OAuth. If multiple rights are selected, the response includes the elements unique for each right.

{% note info %}

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.

{% endnote %}

## Request format {#request-format}

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

{% list tabs %}

- Кecommended method

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

  Authorization: OAuth <OAuth token>
  ```

- The insecure method

   ```
   GET https://login.yandex.ru/info?
    & oauth_token=<OAuth token>
   [& format=json | xml | jwt]
   [& jwt_secret=<secret key>]
   ```
   
   {% note 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.

   {% endnote %}

{% endlist %}

### Request parameters {#request-params}

#|
|| **Parameter** | **Value** | **Description** ||
|| `oauth_token` | <OAuth token> | The OAuth token allowing to access the user's account data via API Yandex ID. The content of the [response](#response-format) 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 | Format for returned data. 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](https://yandex.ru/dev/id/doc/en/tokens/jwt.md). ||
|| `jwt_secret` | <secret key> | 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 {#response-format}

In the response, the service returns a set of [standard](#common) and [additional](#optional) 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](https://yandex.ru/dev/id/doc/en/tokens/jwt.md). Depending on the selected rights, special fields also return in addition to the standard fields.

### Standard response parameters {#common}

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

#|
|| **Property** | **Description** ||
|| `login` | The Yandex username. ||
|| `id` | Unique Yandex user ID. ||
|| `client_id` | The ID of the OAuth app for which the OAuth token in the [request](#request-format) was issued. Available in the [app properties](https://oauth.yandex.com/). 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 {#optional}

Additional response fields depend on the rights selected when [registering the app](https://yandex.ru/dev/id/doc/en/register-client.md#access) at Yandex OAuth and granted by the OAuth token:

* [Missing rights from theAPI Yandex ID section](#norights)

* [Access to email address](#email-access)

* [Access to profile picture](#avatar-access)

* [Access to date of birth](#birthday-access)

* [Access to username, full name, and gender](#name-access)

* [Access to the phone number](#phone-access)

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

#### Missing rights from theAPI Yandex ID section {#norights}

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:

{% list tabs %}

- In JSON format

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

- XML format

   ```xml
   <?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>
   ```

- JWT format

   ```json
   {
      "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"
   }
   ```

{% endlist %}

The response contains the [standard set of fields](#common).

#### Access to email address {#email-access}

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

{% list tabs %}

- In JSON format

   ```json
   {
      "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 format

   ```xml
   <?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>
   ```

- JWT format

   ```json
   {
      "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"
   }        
   ```

{% endlist %}

The response contains the [standard set of fields](#common) as well as advanced parameters:

#|
|| **Property** | **Description** ||
|| `emails` | 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. ||
|#

#### Access to profile picture {#avatar-access}

For a request with an OAuth token that has the **User's profile picture** access right, the API returns the following response:

{% list tabs %}

- In JSON format

   ```json
   {
      "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 format

   ```xml
   <?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>
   ```

- JWT format

   ```json
   {
      "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"
   }     
   ```

{% endlist %}

The response contains the [standard set of fields](#common) as well as advanced parameters:

#|
|| **Property** | **Description** ||
|| `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.
The profile picture with this ID can be downloaded via a link that looks like this:

```
https://avatars.yandex.net/get-yapic/<avatar ID>/<size>
```
If the profile picture with the passed ID is missing, a stub of the specified size will be found by the link.

{% cut "Available sizes" %}

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.

{% endcut %} 

||
|| `avatar_id` | Same as default_avatar_id. The field is only available in JWT format. ||
|#

#### Access to date of birth {#birthday-access}

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

{% list tabs %}

- In JSON format

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

- XML format

   ```xml
   <?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>
   ```

- JWT format

   ```json
   {
      "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"
   }    
   ```

{% endlist %}

The response contains a [standard set of fields](#common) and an additional parameter:

#|
|| **Property** | **Description** ||
|| `birthday` | The user's date of birth, in the format YYYY-MM-DD.

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. ||
|#

#### Access to username, full name, and gender {#name-access}

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:

{% list tabs %}

- In JSON format

   ```json
   {
      "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 format

   ```xml
   <?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>
   ```

- JWT format

   ```json
   {
      "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"
   }        
   ```

{% endlist %}

The response contains the [standard set of fields](#common) as well as advanced 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` | The name that is 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 of the first and last names are presented in Unicode format. ||
|| `sex` | The 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. ||

|| `gender` | Same as **sex**. The field is only available in JWT format. ||
|#

#### Access to the phone number {#phone-access}

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

{% list tabs %}

- In JSON format

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

- XML format

   ```xml
   <?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>
   ```

- JWT format

   ```json
   {
      "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"
   }        
   ```

{% endlist %}

The response contains the [standard set of fields](#common) as well as advanced parameters:

#|
|| **Property** | **Description** ||
|| `default_phone` | The default phone number for contacting the user. The field contains the following parameters: 
* **id**: Phone number ID.
* **number**: The user's phone number. ||
|#

### Example {#all-rights}

If the app has an OAuth token that grants the app all the API Yandex ID rights, the response contains all the [standard](#common) and [advanced](#optional) parameters:

{% list tabs %}

- In JSON format

   ```json
   {
      "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 format

   ```xml
   <?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>
   ```

- JWT format

   ```json
   {
      "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"
   }
   ```

{% endlist %}