Авторизация в сервисах Райффайзен Банка
OpenAPI 1.0.0
API получения токенов для доступа к сервисам Райффайзен Банка по Authorization Code Flow (по протоколам OAuth 2.0 и OpenID Connect 1.0).
Варианты
- Паблик
Операции API
GET /authorize — Запрос на авторизацию (Code Flow)
Запрос инициирует процесс аутентификации пользователя (формируется клиентским приложением).
{
"operationId": "authorize",
"summary": "Запрос на авторизацию (Code Flow)",
"tags": [
"Аутентификация"
],
"description": "Запрос инициирует процесс аутентификации пользователя \n(формируется клиентским приложением).",
"parameters": [
{
"name": "response_type",
"in": "query",
"required": true,
"description": "Тип ответа, для Code Flow необходимо передавать `code`.",
"schema": {
"type": "string",
"enum": [
"code"
],
"example": "code"
}
},
{
"name": "client_id",
"in": "query",
"required": true,
"description": "Идентификатор клиента (выдается Райффайзен Банком).",
"schema": {
"type": "string",
"example": "a12b123b-0a12-3b4c-123a-12a3456789b1"
}
},
{
"name": "redirect_uri",
"in": "query",
"required": true,
"description": "URI, на который будет перенаправлен пользователь после успешной авторизации.\nДолжен быть зарегистрирован в сервисе аутентификации Райффайзен Банка для вашего `client_id`.",
"schema": {
"type": "string",
"format": "uri",
"example": "https://example.ru/callback"
}
},
{
"name": "scope",
"in": "query",
"required": true,
"description": "Запрашиваемые привилегии доступа. \nЗначения указываются через пробел, обязательно должно быть указано значение openid.",
"schema": {
"type": "string",
"example": "openid profile email phone"
}
},
{
"name": "state",
"in": "query",
"required": true,
"description": "Строка для защиты от CSRF-атак, генерируется клиентом.\nВозвращается в неизменном виде после авторизации.",
"schema": {
"type": "string",
"example": "random-state-123"
}
},
{
"name": "nonce",
"in": "query",
"required": true,
"description": "Строка для защиты от replay-атак, генерируется клиентом.\nДобавляется в ID-токен.",
"schema": {
"type": "string",
"example": "random-nonce-456"
}
},
{
"name": "code_challenge",
"in": "query",
"required": true,
"description": "Хэш значения `code_verifier` по стандарту PKCE (RFC 7636):\n`BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))`.",
"schema": {
"type": "string",
"example": "ewliMz7SBtJdHLlNuuJLdzu-gRs2olJQ24AQ8GTS6Qo"
}
},
{
"name": "code_challenge_method",
"in": "query",
"required": true,
"description": "Метод хэширования `code_verifier`. Поддерживается только `S256`.",
"schema": {
"type": "string",
"enum": [
"S256"
],
"example": "S256"
}
}
],
"responses": {
"303": {
"description": "Редирект для продолжения аутентификации пользователя.",
"headers": {
"Location": {
"description": "URI страницы для ввода аутентификационных данных пользователя (/signin)",
"schema": {
"type": "string",
"example": "/signin"
}
},
"Set-Cookie": {
"description": "Куки (например, SESSION, FLASH, Prefer-Auth-Type, Raiff-Device-Id), \nкоторые сервис аутентификации отправляет клиенту для корректного отображения форм аутентификации.",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Запрос некорректен.",
"content": {
"text/plain": {
"schema": {
"type": "string"
},
"examples": {
"MissingClientId": {
"summary": "не указан client_id",
"value": "missing client id"
},
"MissingRedirectionUri": {
"summary": "не указан redirect_uri",
"value": "missing redirection URI"
},
"MismatchingRedirectionUri": {
"summary": "указанный redirect_uri не зарегистрирован для данного client_id",
"value": "mismatching redirection URI for given client"
}
}
}
}
}
}
}GET /signin — Форма аутентификации
Запрос html-страницы с формой для ввода аутентификационных данных пользователя (логина и пароля или номера телефона), отправляется браузером автоматически в результате выполнения запроса GET /authorize.
{
"operationId": "signin",
"summary": "Форма аутентификации",
"tags": [
"Аутентификация"
],
"description": "Запрос html-страницы с формой для ввода \nаутентификационных данных пользователя (логина и пароля или номера телефона),\nотправляется браузером автоматически в результате выполнения запроса GET /authorize.",
"parameters": [
{
"name": "SESSION",
"in": "cookie",
"required": true,
"description": "Служебная кука сервиса аутентификации, \nзадается сервисом аутентификации в результате выполнения запроса GET /authorize.",
"schema": {
"type": "string"
}
},
{
"name": "FLASH",
"in": "cookie",
"required": false,
"description": "Служебная кука сервиса аутентификации, \nзадается сервисом аутентификации в результате взаимодействия с пользователем.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Форма ввода аутентификационных данных.",
"headers": {
"Set-Cookie": {
"description": "Куки (SESSION, FLASH, csrfToken), \nкоторые сервис аутентификации отправляет клиенту для корректного отображения форм аутентификации.",
"schema": {
"type": "string"
}
}
}
},
"303": {
"description": "Редирект для продолжения аутентификации пользователя.",
"headers": {
"Location": {
"description": "URI клиентского приложения для перезапуска процесса аутентификации \n(в случае длительного бездействия пользователя или при передаче некорректных параметров в куках).",
"schema": {
"type": "string",
"example": "https://example.ru/callback"
}
}
}
}
}
}POST /login — Проверка логина и пароля
Запрос на проверку введенных пользователем логина и пароля.
{
"operationId": "login",
"summary": "Проверка логина и пароля",
"tags": [
"Аутентификация"
],
"description": "Запрос на проверку введенных пользователем логина и пароля.",
"requestBody": {
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"properties": {
"login": {
"description": "Логин пользователя \n(в качестве логина также может использоваться email или номер телефона).",
"type": "string"
},
"password": {
"description": "Пароль пользователя.",
"type": "string"
},
"locale": {
"description": "Локаль выбранная пользователем на форме аутентификации.",
"type": "string",
"enum": [
"ru",
"en"
],
"example": "ru"
},
"g-recaptcha-response": {
"description": "Решение Google reCAPTCHA на форме аутентификации.\nКапча требуется (и отображается на форме аутентификации) в том случае, \nкогда сервис аутентификации фиксирует большое количество неудачных попыток входа \n(по одному логину или с одного IP-адреса).",
"type": "string"
}
},
"required": [
"login",
"password"
]
}
}
}
},
"parameters": [
{
"name": "csrfToken",
"in": "query",
"required": true,
"description": "CSRF-токен, который был указан на форме аутентификации \n(возвращается в результате выполнения запроса GET /signin).",
"schema": {
"type": "string"
}
},
{
"name": "SESSION",
"in": "cookie",
"required": true,
"description": "Служебная кука сервиса аутентификации, \nзадается сервисом аутентификации в результате выполнения запроса GET /signin.",
"schema": {
"type": "string"
}
},
{
"name": "FLASH",
"in": "cookie",
"required": false,
"description": "Служебная кука сервиса аутентификации, \nзадается сервисом аутентификации в результате взаимодействия с пользователем.",
"schema": {
"type": "string"
}
}
],
"responses": {
"303": {
"description": "Редирект для завершения аутентификации пользователя.",
"headers": {
"Location": {
"description": "В зависимости от результата проверки пароля возвращается разный URI с разными параметрами.\n\nЕсли пользователь успешно аутентифицирован, то возвращается\nURI клиентского приложения (указанный в параметре `redirect_uri` запроса GET /authorize)\nс параметрами для завершения процесса аутентификации:\n\n- `code` (Authorization Code для обмена на токены)\n- `state` (должен совпадать с тем значением, что было указано в запросе GET /authorize).\n\nВ случае ошибки возвращается URI на форму аутентификации (/signin) для повторной попытки.",
"schema": {
"type": "string",
"example": "https://example.ru/callback?code=yl4jA9kJFj5qQSRdoCRlYId9yAxfBDZy-MhfKI4bpeI&state=random-state-123"
}
},
"Set-Cookie": {
"description": "Куки (например, SESSION, FLASH, csrfToken), \nкоторые сервис аутентификации отправляет клиенту для корректного отображения форм аутентификации.",
"schema": {
"type": "string"
}
}
}
}
}
}POST /token — Получение и обновление токенов
Получение токенов по Authorization Code (`grant_type=authorization_code`) или обновление токенов по Refresh Token (`grant_type=refresh_token`). Требуется Basic Authentication для клиентского приложения: Authorization: Basic Base64(client_id:client_secret).
{
"operationId": "token",
"summary": "Получение и обновление токенов",
"tags": [
"Аутентификация"
],
"description": "Получение токенов по Authorization Code (`grant_type=authorization_code`) \nили обновление токенов по Refresh Token (`grant_type=refresh_token`).\n\nТребуется Basic Authentication для клиентского приложения: Authorization: Basic Base64(client_id:client_secret).",
"security": [
{
"basicAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"properties": {
"grant_type": {
"type": "string",
"description": "Тип взаимодействия, в рамках которого происходит получение токенов:\nauthorization_code для получения токенов по Authorization Code (Code Flow)\nrefresh_token для получения новых токенов по Refresh токену",
"enum": [
"authorization_code",
"refresh_token"
],
"example": "authorization_code"
},
"code": {
"type": "string",
"description": "Authorization Code (обязательный параметр для grant_type=authorization_code), \nзначение переданное в параметре code после успешной аутентификации пользователя и \nперенаправлении на redirect_uri клиентского приложения.",
"example": "yl4jA9kJFj5qQSRdoCRlYId9yAxfBDZy"
},
"redirect_uri": {
"type": "string",
"description": "URI клиентского приложения (обязательный параметр для grant_type=authorization_code).\nДолжен совпадать со значением redirect_uri из запроса GET /authorize.",
"format": "uri"
},
"code_verifier": {
"type": "string",
"description": "Случайная строка (обязательный параметр для grant_type=authorization_code), \nкоторая согласно стандарту PKCE (RFC 7636) использовалась для генерации \nзначения code_challenge из запроса GET /authorize."
},
"refresh_token": {
"type": "string",
"description": "Refresh Token (обязательный параметр для grant_type=refresh_token)."
}
},
"required": [
"grant_type"
]
},
"examples": {
"AuthorizationCode": {
"summary": "Получение токенов по Authorization Code",
"value": {
"grant_type": "authorization_code",
"code": "yl4jA9kJFj5qQSRdoCRlYId9yAxfBDZy",
"code_verifier": "ACbrszxo9MTPRDHBej_Hyjftt9jc2r2aQZurfomS_ct",
"redirect_uri": "https://example.ru/callback"
}
},
"RefreshToken": {
"summary": "Обновление токенов по Refresh Token",
"value": {
"grant_type": "refresh_token",
"refresh_token": "your_refresh_token"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Успешно выданы токены",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"access_token": {
"type": "string",
"description": "Access Token в формате JWT."
},
"token_type": {
"type": "string",
"enum": [
"Bearer"
],
"description": "Тип токена (всегда `Bearer`).",
"example": "Bearer"
},
"refresh_token": {
"type": "string",
"description": "Refresh Token для обновления токенов.\nПри обновлении токенов по Refresh Token будет выдан новый Refresh Token с таким же сроком действия."
},
"id_token": {
"type": "string",
"description": "ID Token в формате JWT с информацией о пользователе."
}
}
},
"example": {
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"refresh_token": "d8f7a6b5c4e3f2a1b0c9d8e7f6a5b4c3",
"id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}
}
}
},
"400": {
"description": "Некорректный запрос",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorWithDescriptionResponseDTO"
},
"examples": {
"InvalidRequest": {
"summary": "Некорректный запрос",
"value": {
"error": "invalid_request",
"error_description": "Invalid request"
}
}
}
}
}
},
"401": {
"description": "Ошибка авторизации",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorWithDescriptionResponseDTO"
},
"examples": {
"InvalidRequest": {
"summary": "Некорректный Refresh токен или запрос выполняется слишком часто",
"value": {
"error": "invalid_request",
"error_description": "Invalid request"
}
},
"InvalidClient": {
"summary": "Некорректны авторизационные данные клиента (в заголовке Authorization)",
"value": {
"error": "invalid_client",
"error_description": "Client authentication failed"
}
}
}
}
}
}
}
}Схемы и примеры
{
"securitySchemes": {
"basicAuth": {
"type": "http",
"scheme": "basic",
"description": "Basic Authentication: `Authorization: Basic Base64(client_id:client_secret)`.\n\nПример генерации:\n```\nclient_id = a12b123b-0a12-3b4c-123a-12a3456789b1\nclient_secret = clientsecret7Fjfp0ZBr1KtDRbnfV\nBase64(client_id:client_secret) = YTEyYjEyM2ItMGExMi0zYjRjLTEyM2EtMTJhMzQ1Njc4OWIxOmNsaWVudHNlY3JldDdGamZwMFpCcjFLdERSYm5mVg\n```"
}
},
"schemas": {
"ErrorWithDescriptionResponseDTO": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"error_description": {
"type": "string"
}
},
"required": [
"error",
"error_description"
]
}
}
}