Яндекс ID

https://yandex.ru/dev/id/doc/ru/
Admin
Яндекс ID — это единый аккаунт на Яндексе. API Яндекс ID позволяет настроить авторизацию...
Tokens:5,565
Snippets:14
Trust Score:9.9
Update:11 months ago
Show doc for...
Tokens:
Raw
### Token Exchange Response Format

Source: https://yandex.ru/dev/id/doc/ru/codes/code-url

Example of successful OAuth token response URL format showing code and state parameters. Used for successful authorization code exchange with optional CSRF protection state parameter.

```http
http://www.example.com/token?code=<код подтверждения>
[& state=<значение параметра state в запросе>]
```

--------------------------------

### Get Authorization Code

Source: https://yandex.ru/dev/id/doc/ru/codes/code-url

This endpoint is used to initiate the OAuth flow and obtain an authorization code. The user is redirected to this URL to confirm access to their data.

```APIDOC
## GET /authorize

### Description
Initiates the OAuth flow to obtain an authorization code. The user is redirected to this URL to confirm access to their data. The code is returned in the redirect URI.

### Method
GET

### Endpoint
https://oauth.yandex.ru/authorize

### Parameters
#### Query Parameters
- **response_type** (string) - Required - Must be set to "code" to request an authorization code.
- **client_id** (string) - Required - The client ID of your application, found in the Yandex OAuth application settings.
- **redirect_uri** (string) - Optional - The URL to which the user will be redirected after authorization. Must be registered in your application's settings.
- **device_id** (string) - Optional - An identifier for the device.
- **device_name** (string) - Optional - The name of the device.
- **login_hint** (string) - Optional - A hint for the user's login name or email address.
- **scope** (string) - Optional - A space-separated list of requested permissions.
- **optional_scope** (string) - Optional - A space-separated list of optional permissions.
- **force_confirm** (string) - Optional - If set to "yes", forces the user to re-confirm access even if they have already granted it.
- **state** (string) - Optional - An arbitrary string to maintain state between the request and callback. Useful for preventing cross-site request forgery.
- **code_challenge** (string) - Optional - A challenge generated using the `code_verifier` for PKCE extension.
- **code_challenge_method** (string) - Optional - The method used to generate the `code_challenge` (e.g., "S256").

### Request Example
```
https://oauth.yandex.ru/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI
```

### Response
#### Success Response (302 Found)
- **Location** (string) - The redirect URL containing the authorization code in the query parameters (e.g., `YOUR_REDIRECT_URI?code=AUTHORIZATION_CODE`).

#### Response Example
(Redirect to `YOUR_REDIRECT_URI?code=AUTHORIZATION_CODE`)
```

--------------------------------

### GET https://oauth.yandex.ru/authorize

Source: https://yandex.ru/dev/id/doc/ru/codes/code-url

The Yandex OAuth authorization endpoint allows applications to request access tokens by redirecting users to this URL with various query parameters. This documentation covers the additional parameters that can be included to control device binding, user login hints, scopes, and other behaviors.

```APIDOC
## GET https://oauth.yandex.ru/authorize

### Description
This endpoint is used to initiate the OAuth authorization flow for Yandex services. By including additional query parameters, applications can specify device details, user account hints, access scopes, and other options to tailor the authorization process.

### Method
GET

### Endpoint
https://oauth.yandex.ru/authorize

### Parameters
#### Query Parameters
- **device_id** (string) - Optional - Unique identifier for the device requesting the token. Must be 6-50 printable ASCII characters. Ensures token uniqueness per device. If provided without device_name, the token is marked for an unknown device. Limits: max 30 device-bound tokens per app per user, oldest expires automatically.
- **device_name** (string) - Optional - Display name for the device, up to 100 characters. Recommended for mobile devices (e.g., model + OS). Ignored if device_id is not provided; in that case, only a standard token is issued.
- **redirect_uri** (string) - Optional - URL to redirect the user after authorization. Must match one configured in the app settings. Defaults to the first configured Redirect URI.
- **login_hint** (string) - Optional - Login or email for the target Yandex account. Helps pre-fill the login form. If the user is not logged in with that account, the form shows with the hint. Does not force use of the hinted account.
- **scope** (string) - Optional - Space-separated list of access rights required by the app. Must be from the app's registered rights. Available rights info at https://oauth.yandex.ru/client/<client_id>/info. Defaults to registered rights if scope and optional_scope are omitted.
- **optional_scope** (string) - Optional - Space-separated list of optional rights. User can choose to grant them. Combined with scope; duplicates are treated as optional.
- **force_confirm** (boolean) - Optional - Forces re-confirmation of access permissions, even if already granted. Accepts 'yes', 'true', or '1'; other values ignored. Useful for account switching.
- **state** (string) - Optional - State string returned unchanged, up to 1024 characters. Used for CSRF protection or user identification.

### Request Example
https://oauth.yandex.ru/authorize?response_type=code&client_id=<client_id>&device_id=abc123&device_name=My%20Device&redirect_uri=https%3A%2F%2Fexample.com&login_hint=user%40yandex.ru&scope=login%20email&optional_scope=avatar&force_confirm=yes&state=xyz123

### Response
#### Success Response (302 Redirect)
Redirects to the specified redirect_uri with authorization code in query parameters.

#### Error Response (Various)
Errors may occur if parameters are invalid, such as invalid scopes or mismatched redirect_uri. Specific error codes are returned in the redirect query.

#### Response Example
HTTP/1.1 302 Found
Location: https://example.com/?code=authorization_code&state=xyz123
```

--------------------------------

### POST /oauth/token

Source: https://yandex.ru/dev/id/doc/ru/codes/code-url

Retrieves an OAuth access token using the authorization code flow. Returns token details on success or an error object on failure.

```APIDOC
## POST /oauth/token

### Description
Retrieves an OAuth access token using the authorization code flow. Returns token details on success or an error object on failure.

### Method
POST

### Endpoint
/oauth/token

### Parameters
#### Path Parameters
- *none* (none) - None - No path parameters.

#### Query Parameters
- *none* (none) - None - No query parameters.

#### Request Body
- **grant_type** (string) - Required - Must be set to `authorization_code`.
- **code** (string) - Required - 7‑digit verification code obtained from the user.
- **client_id** (string) - Required - Application identifier.
- **client_secret** (string) - Required - Application secret.
- **redirect_uri** (string) - Optional - Must match the redirect URI registered for the application.

### Request Example
{
  "grant_type": "authorization_code",
  "code": "1234567",
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "redirect_uri": "https://example.com/callback"
}

### Response
#### Success Response (200)
- **token_type** (string) - Token type, always `bearer`.
- **access_token** (string) - OAuth token with the requested scopes.
- **expires_in** (integer) - Lifetime of the access token in seconds.
- **refresh_token** (string) - Token used to obtain a new access token; its lifetime matches the access token.
- **scope** (string) - Scopes granted to the token.

#### Response Example
{
  "token_type": "bearer",
  "access_token": "AQAAAACy1C6ZAAAAfa6vDLuItEy8pg-iIpnDxIs",
  "expires_in": 124234123534,
  "refresh_token": "1:GN686QVt0mmakDd9:A4pYuW9LGk0_UnlrMIWklkAuJkUWbq27loFekJVmSYrdfzdePBy7:A-2dHOmBxiXgajnD-kYOwQ",
  "scope": "login:info login:email login:avatar"
}

### Error Handling
#### Error Response (4xx)
- **error** (string) - Machine‑readable error code.
- **error_description** (string) - Human‑readable description of the error.

#### Possible Error Codes
- `authorization_pending` — User has not entered the confirmation code.
- `bad_verification_code` — The `code` parameter is not a 7‑digit number.
- `invalid_client` — Application with the given `client_id` not found or blocked, or `client_secret` is invalid.
- `invalid_grant` — Invalid or expired verification code.
- `invalid_request` — Malformed request (missing or duplicate parameters, or not in request body).
- `invalid_scope` — Application scopes changed after code generation.
- `unauthorized_client` — Application rejected or pending moderation, or blocked.
- `unsupported_grant_type` — Invalid `grant_type` value.
- `Basic auth required` — `Authorization` header is not "Basic".
- `Malformed Authorization header` — Header not in `<client_id>:<client_secret>` format or not Base64‑encoded.

#### Error Response Example
{
  "error": "invalid_grant",
  "error_description": "The provided verification code is invalid or expired."
}
```

--------------------------------

### Token Exchange API

Source: https://yandex.ru/dev/id/doc/ru/codes/code-url

This API endpoint allows you to exchange a confirmation code for an OAuth token. It requires specific grant types and can optionally include client identifiers, secrets, and device information.

```APIDOC
## POST /token

### Description
This endpoint facilitates the exchange of a confirmation code for an OAuth token. It is part of the Yandex OAuth flow and requires specific parameters to be sent in the request body.

### Method
POST

### Endpoint
https://oauth.yandex.ru/token

#### Query Parameters
- **grant_type** (string) - Required - The grant type for the request. Must be 'authorization_code' for this flow.
- **code** (string) - Required - The confirmation code obtained from Yandex OAuth. This code has a 10-minute lifespan.
- **client_id** (string) - Optional - The identifier of your application.
- **client_secret** (string) - Optional - The secret key for your application.
- **device_id** (string) - Optional - The identifier for the device making the request.
- **device_name** (string) - Optional - The name of the device making the request.
- **code_verifier** (string) - Optional - The verifier used with the 'code_challenge' for PKCE extension.

### Request Example
```
POST /token HTTP/1.1
Host: https://oauth.yandex.ru/
Content-type: application/x-www-form-urlencoded
Content-Length: <length_of_request_body>
[Authorization: Basic <base64_encoded_client_id:client_secret>]

grant_type=authorization_code
& code=<confirmation_code>
[& client_id=<application_id>]
[& client_secret=<secret_key>]
[& device_id=<device_id>]
[& device_name=<device_name>]
[& code_verifier=<verifier>]
```

### Response
#### Success Response (200)
- **access_token** (string) - The OAuth access token.
- **expires_in** (integer) - The lifespan of the access token in seconds.
- **token_type** (string) - The type of token, usually 'Bearer'.
- **refresh_token** (string) - A token to obtain a new access token when the current one expires.
- **scope** (string) - The scope of the granted permissions.

#### Response Example
```json
{
  "access_token": "your_access_token",
  "expires_in": 3600,
  "token_type": "Bearer",
  "refresh_token": "your_refresh_token",
  "scope": "login:email"
}
```

#### Error Response
If the confirmation code could not be issued, Yandex OAuth will indicate an error code and description in the URL.

##### Possible Error Codes:
- `unauthorized_client`: The application was rejected during moderation or is awaiting moderation. Also returned if the application is blocked.

```
http://www.example.com/token?error=<error_code>
 & error_description=<error_description>
[& state=<state_parameter_value>]
```
```

--------------------------------

### Authorization Code Token Exchange Request

Source: https://yandex.ru/dev/id/doc/ru/codes/code-url

POST request format for exchanging authorization code for OAuth token. Supports both Basic Auth and client credentials in body. Includes PKCE verification, device identification, and standard OAuth 2.0 authorization code grant type parameters.

```http
POST /token HTTP/1.1
Host: https://oauth.yandex.ru/
Content-type: application/x-www-form-urlencoded
Content-Length: <длина тела запроса>
[Authorization: Basic <закодированная методом base64 строка `client_id:client_secret`>]

   grant_type=authorization_code
 & code=<код подтверждения>
[& client_id=<идентификатор приложения>]
[& client_secret=<секретный ключ>]
[& device_id=<идентификатор устройства>]
[& device_name=<имя устройства>]
[& code_verifier=<верификатор>]
```

--------------------------------

### Exchange Authorization Code for OAuth Token

Source: https://yandex.ru/dev/id/doc/ru/codes/code-url

This endpoint exchanges the obtained authorization code for an OAuth access token. This is a POST request made by your application's backend.

```APIDOC
## POST /token

### Description
Exchanges an authorization code for an OAuth access token. This is a POST request that your application makes to the Yandex OAuth server.

### Method
POST

### Endpoint
https://oauth.yandex.ru/token

### Parameters
#### Request Body
- **grant_type** (string) - Required - Must be set to "authorization_code".
- **code** (string) - Required - The authorization code obtained from the `/authorize` endpoint.
- **client_id** (string) - Required - The client ID of your application.
- **client_secret** (string) - Required - The client secret of your application. Keep this secret and do not expose it.
- **redirect_uri** (string) - Optional - The same redirect URI used in the authorization request.

### Request Example
```json
{
  "grant_type": "authorization_code",
  "code": "AUTHORIZATION_CODE",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}
```

### Response
#### Success Response (200 OK)
- **access_token** (string) - The OAuth access token.
- **expires_in** (integer) - The lifetime of the access token in seconds.
- **token_type** (string) - The type of the token, usually "bearer".
- **refresh_token** (string) - The refresh token, used to obtain a new access token when the current one expires.
- **scope** (string) - The scope of permissions granted by the token.

#### Response Example
```json
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "expires_in": 3600,
  "token_type": "bearer",
  "refresh_token": "YOUR_REFRESH_TOKEN",
  "scope": "login:email profile"
}
```
```

--------------------------------

### OAuth Error Response Format

Source: https://yandex.ru/dev/id/doc/ru/codes/code-url

Error response format for failed OAuth token requests including error codes and descriptions. Supports standard OAuth 2.0 error handling with optional state parameter for request correlation.

```http
http://www.example.com/token?error=<код ошибки>
 & error_description=<описание ошибки>
[& state=<значение параметра state в запросе>]
```

--------------------------------

### POST /token

Source: https://yandex.ru/dev/id/doc/ru/codes/code-url

Exchanges an authorization code for an access token in Yandex OAuth. Supports additional parameters for device binding and PKCE to secure the flow. Parameters are sent in the request body as URL-encoded form data.

```APIDOC
## POST /token

### Description
This endpoint is used to obtain an access token by exchanging an authorization code obtained from the authorization server. It supports standard OAuth 2.0 flows with extensions for device-specific tokens and Proof Key for Code Exchange (PKCE) to protect against authorization code interception.

### Method
POST

### Endpoint
/token

### Parameters

#### Request Body
Parameters are sent as URL-encoded form data in the request body. Standard parameters like `grant_type`, `code`, and `redirect_uri` are required, with the following additional optional parameters:

- **client_id** (string) - Required if not using Authorization header - Application identifier from Yandex OAuth app properties.
- **client_secret** (string) - Optional (required without PKCE) - Secret key from app properties. Omitted if using PKCE with `code_verifier`.
- **device_id** (string) - Optional - Unique device identifier (UUID recommended, 6-50 printable ASCII characters). Limits to 30 tokens per user-device.
- **device_name** (string) - Optional - Device name for user display (up to 100 characters). Ignored without `device_id`.
- **code_verifier** (string) - Optional (for PKCE) - Random string verifier used to generate `code_challenge` in the authorization request.

Alternatively, encode `client_id:client_secret` in Base64 and send as Basic Auth in the `Authorization` header; body parameters for client credentials are then ignored.

### Request Example
{
  "grant_type": "authorization_code",
  "code": "SAMPLE_CODE",
  "redirect_uri": "https://example.com/callback",
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "device_id": "unique-device-uuid",
  "device_name": "My Mobile Device",
  "code_verifier": "random-verifier-string"
}

### Response
#### Success Response (200)
Returns a JSON object with access token, token type, expires_in, and optional refresh_token. For device-bound tokens, the token is tied to the specified device.

#### Response Example
{
  "access_token": "SAMPLE_ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "SAMPLE_REFRESH_TOKEN"
}
```

--------------------------------

### Yandex OAuth Success Response (JSON)

Source: https://yandex.ru/dev/id/doc/ru/codes/code-url

This JSON object represents a successful response from the Yandex OAuth server, containing the access token, refresh token, and their respective lifetimes. It includes metadata like token type and requested scopes.

```json
{
  "token_type": "bearer",
  "access_token": "AQAAAACy1C6ZAAAAfa6vDLuItEy8pg-iIpnDxIs",
  "expires_in": 124234123534,
  "refresh_token": "1:GN686QVt0mmakDd9:A4pYuW9LGk0_UnlrMIWklkAuJkUWbq27loFekJVmSYrdfzdePBy7:A-2dHOmBxiXgajnD-kYOwQ",
  "scope": "login:info login:email login:avatar"
}
```

--------------------------------

### Yandex OAuth Error Response (JSON)

Source: https://yandex.ru/dev/id/doc/ru/codes/code-url

This JSON object indicates an error during the Yandex OAuth process. It provides a human-readable description of the error and a corresponding error code for programmatic handling.

```json
{
   "error_description": "<описание ошибки>",
   "error": "<код ошибки>"
}
```
Tokens:
Raw