Получение токенов доступа

Обновлено 29 ноября 2024

/ic/sso/api/v2/oauth/token

Запрос позволяет обменять код авторизации на токены доступа (access_token, refresh_token, id_token), а также обновить access_token.

Для обращения к ресурсу необходимо отправлять запрос на:

Тестовый контур https://iftfintech.testsbi.sberbank.ru:9443
Промышленный контур https://fintech.sberbank.ru:9443

Получение access token, refresh token, id token

Request

/ic/sso/api/v2/oauth/token

Модель
Пример

Наименование	Тип	Формат	Regexp	Обязательность	Описание
HEADER
Content-Type	string	string	^(application/json\|text/plain\|application/xml\|multipart/form-data\|application/x-www-form-urlencoded)$	required	Тип данных, которые передаются в теле запроса. Должен содержать значение application/x-www-form-urlencoded.
Accept	string	string	^(application/json\|application/jose)	optional	Указывает на формат данных, который вы готовы принять от Банка. Если ответ не требуется в зашифрованном виде, то может быть не указан или передан со значением application/json. Если необходимо получить ответ на запрос токена в зашифрованном виде, то необходимо передать параметр со значением application/jose.
From URL Encoded
grant_type	string	string	^(authorization_code\|refresh_token)$	required	Указывает тип предоставления, который используется для запроса токена доступа Значение должно быть authorization_code
code	string	string	^[a-zA-Z0-9]{38}$	required	Код авторизации. В параметре необходимо использовать значение code, полученное на адрес redirect_uri при успешной аутентификации пользователя по URL аутентификации `/v2/oauth/authorize`. Каждый code может быть использован только один раз. Например, если при запросе access_token по коду авторизации была допущена ошибка в каком либо из параметров и передано значение code, то повторное использование данного значения code уже будет недопустимо.
client_id	string	string	^[a-zA-Z0-9]+$	required	Уникальный идентификатор вашей Платформы, полученный при подключении к Sber API
redirect_uri	string	string	^(https?:\/\/)?(www.)?([a-z0-9-.]+.[a-z]{2,3})(:[0-9]{1,5})?\/?.*$	required	Адрес вашей Платформы, на который СберБизнес ID возвращает пользователя при успешной аутентификации. Должен в точности совпадать со значением, переданным ранее при вызове ресурса `/v2/oauth/authorize` Пример: Если в redirect_uri было указано https://example.ru/auth/login/register, то точно такое же значение должно быть указано при запросе `/v2/oauth/token`, даже если зарегистрирован redirect_uri = https://example.ru/auth/login
client_secret	string	string	^[a-zA-Z0-9]{8,256}$	required	Пароль вашей Платформы. Вы его впервые получаете при подключении к Sber API и в последующем периодически обновляете.
code_verifier	string	string	^[a-zA-Z0-9]+$	optional	Параметр в соответствии с надстройкой PKCE над протоколом OAuth 2.0. Раскодированное значение code_challenge переданное ранее при вызове ресурса /authorize. См. правила формирования параметра в PKCE. Становится обязательным, если при регистрации платформы настройка PKCE была подключена или при вызове ресурса `/v2/oauth/authorize` параметр code_challenge был передан.

POST /ic/sso/api/v2/oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Accept: */*

grant_type=authorization_code&code=abc123def456ghi7893Djkl012mno345pqr678&client_id=92233764567396&redirect_uri=https%3A%2F%2Fwww.sberbank.ru%2Fru%2Fperson&client_secret=vyYPXdBh

Responses

200 (OK)

Модель
Пример

Наименование	Тип	Обязательность	Описание
HEADER
Content-Type	string	required	Если в запросе: - не был передан заголовок Accept или передан в значении application/json, то в ответе параметр будет содержать значение application/json - был передан заголовок Accept в значении application/jose, то в ответе будет указано application/jose и полученное тело ответа потребуется расшифровать.
BODY
{
access_token	string	required	Авторизационный токен доступа
token_type	string	required	Тип токена. Всегда возвращается значение Bearer
expires_in	string	required	Срок жизни токена в секундах. Срок жизни access_token составляет 60 минут.
refresh_token	string	required	Токен обновления. Используется для обновления Access Token. Подробнее про применение значения refresh_token см. в Обновление токена доступа (access_token) Срок жизни refresh_token составляет 180 дней.
scope	string	required	Набор атрибутов (claim) и операций, которые будут доступны Платформе после авторизации клиента.
id_token	string	required	Закодированный в Base64URL набор атрибутов клиента, необходимых для идентификации пользователя. Атрибуты разделены символами «.», каждый необходимо декодировать отдельно.
}

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "scope": "openid ACCEPTANCE_ADVANCE ACCEPTANCE_LETTER BANK_CONTROL_STATEMENT BANK_CONTROL_STATEMENT_CHANGE_APPLICATION BUSINESS_CARDS_TRANSFER BUSINESS_CARD_LIMIT CARD_ISSUE CERTIFICATE_REQUEST CLIENT_TARIFF COLLECTION_ORDERS CONFIRMATORY_DOCUMENTS_INQUIRY CONTRACT_CLOSE_APPLICATION CORPORATE_CARDS CORPORATE_CARD_REQUEST CREDIT_REQUEST CRYPTO_CERT_REQUEST_EIO CURRENCY_NOTICES CURRENCY_OPERATION_DETAILS CURR_BUY CURR_CONTROL_INFO_REQ CURR_CONTROL_MESSAGE_FROM_BANK CURR_CONTROL_MESSAGE_TO_BANK CURR_SELL DEBT_REGISTRY DICT ESTATE_FEED FILES GENERIC_LETTER_FROM_BANK GENERIC_LETTER_TO_BANK GET_ADVANCE_ACCEPTANCES GET_CLIENT_ACCOUNTS GET_CORRESPONDENTS GET_CREDIT_OFFERS GET_CRYPTO_INFO GET_CRYPTO_INFO_EIO GET_CUSTOMER_INFO GET_PARTNER_OFFERS GET_REQUEST_STATISTICS GET_STATEMENT_ACCOUNT GET_STATEMENT_TRANSACTION GET_TARIFF_PLANS GET_TARIFF_PLANS_LIST_AVAILABLE ORDER_MANDATORY_SALE PAYMENTS_REGISTRY PAYMENT_REQUEST_IN PAYMENT_REQUEST_OUT PAYROLL PAY_DOC_CUR PAY_DOC_RU PAY_DOC_RU_INVOICE PAY_DOC_RU_INVOICE_ANY PAY_DOC_RU_INVOICE_BUDGET SALARY_AGREEMENT SALARY_AGREEMENT_REQUEST TARIFF_PLAN_MANAGEMENT TARIFF_PLAN_MANAGEMENT_JWS TARIFF_PLAN_OVER_BILLING_JSON TARIFF_PLAN_OVER_BILLING_JWS name inn email phone_number HashOrgId orgKpp orgFullName OrgName orgOgrn orgActualAddress orgJuridicalAddress accounts terBank offerExpirationDate userPosition userCryptoType individualExecutiveAgency orgOktmo offerSmartCredit summOfferSmartCredit buyOnCreditMmb orgLawForm orgLawFormShort hasActiveCreditLine creditLineAvailableSum",
    "access_token": "abc123def456ghi789jkl6D012mno345pqr678",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "xbgDF3brf456ghi789jkl012fYmno345pqr678",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJnb3N0MzQuMTAtMjAxMiJ9.eyJzdWIiOiI2MjA2Mjg1NDA5ZmNjMjhjZDFmOTZhZjg4MGI1ZjkyNDJiYjZjZGU2NmU3ZGRkZmRmZDNjZGU0YzcyMzcyZWQxIiwiYXVkIjoiOTIyMzM3NjQ1NjczOTYiLCJhY3IiOiJsb2EtMyIsImF6cCI6IjkyMjMzNzY0NTY3Mzk2IiwiYXV0aF90aW1lIjoxNzA2MDE3MTMzLCJhbXIiOiJ7cHdkLCBtY2EsIG1mYSwgb3RwLCBzbXN9IiwiaXNzIjoiaHR0cHM6Ly9lZnMtc2Jib2wtaWZ0LXdlYi50ZXN0c2JpLnNiZXJiYW5rLnJ1Ojk0NDMvaWMiLCJleHAiOjE3MDYwMTc0NTQsImlhdCI6MTcwNjAxNzE1NCwibm9uY2UiOiI4MDAxMmM5Yy0xYjlhLTQ0OWUtYThkNS03NTEwMGVhNjk4YWMifQ.G5PoX66cDvkie6KqdRItbUmb_4QOHZl700gzXUMmldY7Po4Rk_Sw0jM3LNYN2s8NfDe6a1fTF70mR3zOpPFPiA"
}

400 (Bad request)

error	error_description	Описание причины
invalid_grant	Missing grant_type parameter value	Не заполнен обязательный параметр grant_type
invalid_grant	One of the params (code, refresh_token) is required at request	Не заполнен один из обязательных параметров code или refresh_token
invalid_grant	Failed to extract shoulder ID from {0}	В параметре code или refresh_token указано некорректное значение
invalid_grant	Unknown code = '{0}'	Не найдено переданное значение code. Например, потому что срок действия кода истек или по данному коду уже осуществлялся вызов.
invalid_grant	Unknown refresh token = '{0}'	Не найдено переданное значение refresh_token. Например, потому что срок действия токена истек или по данному токену уже был осуществлен обмен на access_token.
invalid_grant	Ext service for authz code '{0}' is blocked	Платформа зарегистрированное по указанному client_id - заблокировано.
invalid_grant	Invalid credentials for authz code '{0}'	При запросе access_token по коду авторизации указан неверный client_secret
invalid_grant	Invalid credentials for refresh_token '{0}'	При запросе access_token по refresh_token указан неверный client_secret
invalid_grant	Redirect uri '{0}' is invalid	Переданный параметр redirect_uri не совпадает со значением полученным ранее при запросе кода авторизации
invalid_grant	Failed to verify code verifier	Хешированное значение code_challenge, полученное в запросе /authorize не совпадает со значением, полученным в параметре code_verifier
invalid_request	Missing parameters: code	В параметре grant_type указано значение authorization_code, но отсутствует значение в параметре code
invalid_request	Missing parameters: refresh_token	В параметре grant_type указано значение refresh_token, но отсутствует значение в параметре refresh_token
invalid_request	Missing parameters: {0}	Отсутствует параметр redirect_uri
invalid_request	client secret expired	Истек срок действия client_secret
invalid_request	Code verifier required	При запросе кода авторизации был указан code_challenge, но в параметрах запроса токена отсутствует параметр code_verifier
invalid_request	Invalid code verifier	Значение code_verifier не отвечает параметрам протокола PKCE
unauthorized_client	Unknown client_id = '{0}'	Переданный client_id не зарегистрирован
unauthorized_client	Client '{0}' is blocked	Платформа зарегистрированное по указанному client_id - заблокировано.
unsupported_grant_type	Grant type '{0}' is not supported"	В параметре grant_type указано значение отличное от authorization_code или refresh_token

Модель
Пример

Наименование	Тип	Обязательность	Описание
{
error	string	required	Ошибка запроса
error_description	string	required	Описание ошибки
}

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
   "error": "invalid_grant",
   "error_description": "Unknown code = '4b133d0f-4ca8-4825-94cb-c687507605d8-2'"
}

403 (Forbidden)

errorCode	errorMsg	Описание причины
requestForbidden	The server configuration prohibits executing a request to the endpoint {0}	На данном сервере запрещен вызов указанного ресурса. Например, вызов ресурса `/v2/oauth/token` осуществляется на домен `https://efs-sbbol-ift-web.testsbi.sberbank.ru:9443`, а должен осуществляться на домен `https://iftfintech.testsbi.sberbank.ru:9443`
certificateNotFound	The certificate was not whitelisted for client_id={0}	Не пройдена проверка сертификата по белому списку

Модель
Пример

Наименование	Тип	Обязательность	Описание
{
errorCode	string	required	Ошибка запроса
errorMsg	string	required	Описание ошибки
}

HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8

{
   "errorCode": "requestForbidden",
   "errorMsg": "The server configuration prohibits executing a request to the endpoint {0}"
}

406 (Not acceptable)

error	error_description	Описание причины
SSOREQUESTED_FORMAT_NOT_ACCEPTABLE_EXCEPTION	JSON	В соответствии с текущими настройками платформы необходимо запрашивать ответ в формате JSON
SSOREQUESTED_FORMAT_NOT_ACCEPTABLE_EXCEPTION	JWE Compact Serialization	В соответствии с текущими настройками платформы необходимо запрашивать ответ в формате JWE Compact Serialization

Модель
Пример

Наименование	Тип	Обязательность	Описание
{
error	string	required	Ошибка запроса
error_description	string	required	Описание ошибки
}

HTTP/1.1 406 Not acceptable
Content-Type: application/json;charset=UTF-8

{
   "error": "SSOREQUESTED_FORMAT_NOT_ACCEPTABLE_EXCEPTION",
   "error_description": "JSON"
}

429 (Too Many Requests)

Cause	Message	Description
TOO_MANY_REQUESTS	Превышен лимит запросов. Повторите операцию позже.	Количество запросов к данному методу за ограниченное время превысило допустимое значение. Пользователю необходимо повторить запрос позднее

Модель
Пример

Наименование	Тип	Обязательность	Описание
Notice{
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

500 (Internal Server Error)

Cause	Message	Description
UNKNOWN_EXCEPTION	Внутренняя ошибка сервера	Сделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.

Модель
Пример

Наименование	Тип	Обязательность	Описание
Notice {
cause	string	optional	Причина или основание сообщения,
referenceId	string	optional	Уникальный идентификатор ошибки (UUID),
message	string	optional	Сообщение,
}

HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
 
{
  "cause": "UNKNOWN_EXCEPTION",
  "referenceId": "9e209109-4b0d-408c-a2fd-e1983c20a65d",
  "message": "Внутренняя ошибка сервера"
}

access_token

Это уникальный идентификатор, который позволяет платформе подтвердить Банку, что клиент дал ему разрешение на доступ к его данным. Он необходим для использования других запросов Sber API.
С момента получения токен доступа (access_token) действителен 60 минут.

refresh_token

access_token имеет временный характер действия (60 минут с момента получения). Для обновления токена доступа необходимо использовать токен обновления (refresh_token).
С момента получения токен обновления (refresh token) действителен 180 дней.

Обязательно предусмотрите механизм обновления токена в пределах срока его действия, в ином случае платформа не сможет совершать операции с данными клиентами.

ID token (/token)

Этот токен используется для подтверждения того, что пользователь успешно прошел процесс авторизации и имеет доступ к запрашиваемым операциям.

ID token представлен в виде JSON Web Token (JWT) и структурой:

Алгоритм подписи и тип токена (Header);
Полезная нагрузка (Payload);
Электронная подпись (Signature).

Каждая часть ответа, разделенная точкой, должна декодироваться отдельно. Для декодирования следует воспользоваться алгоритмом Base64URL Encoding.

При необходимости вы можете настроить процесс проверки подлинности данных. Для этого необходимо вычислить подпись публичным ключом Банка, декодировав блок Header и Payload (содержимое между двумя точками). Далее сравнить полученное значение c блоком Электронная подпись (содержимое после второй точки).

Пример ID Token

Модель
ID token
Структура

Параметр	Описание
HEADER
typ	Тип токена
alg	Алгоритм шифрования
PAYLOAD
acr	Уровень аутентификации пользователя: - acr=loa-2 (пользователь аутентифицируется с помощью устройства защиты) - acr=loa-3 (пользователь использует подтверждение по одноразовому SMS-паролю для аутентификации)
amr	Ресурсы аутентификации: - amr=pwd — пользователь аутентифицируется с помощью устройства защиты; - amr= {pwd, mca, mfa, otp, sms} — пользователь использует подтверждение по одноразовому SMS-паролю для аутентификации
aud	Идентификатор платформы, для которого сформирован ID Token
auth_time	Время аутентификации пользователя в СберБизнес ID. Формат поля Unix time
azp	Идентификатор платформы, для которого сформирован ID Token
exp	Время, после которого ID Token не принимается для обработки. Формат поля Unix time
iat	Время формирования ID Token. Формат поля Unix time
iss	URL сервиса, сформировавшего ID Token
nonce	Значение параметра nonce, полученного при запросе авторизации `/v2/oauth/authorize`
sub	Уникальный идентификатор пользователя
SIGNATURE
Массив байт электронной подписи	Проверка электронной подписи, полученной в ID Token (содержимое ответа ID Tokena после второй точки), выполняется, используя алгоритм, указанный в параметре заголовка JWT alg. Платформе необходимо проверить подпись сертификатом Банка

eyJ0eXAiOiJKV1QiLCJhbGciOiJnb3N0MzQuMTAtMjAxMiJ9.eyJzdWIiOiI2MjA2Mjg1NDA5ZmNjMjhjZDFmOTZhZjg4MGI1ZjkyNDJiYjZjZGU2NmU3ZGRkZmRmZDNjZGU0YzcyMzcyZWQxIiwiYXVkIjoiOTIyMzM3NjQ1NjczOTYiLCJhY3IiOiJsb2EtMyIsImF6cCI6IjkyMjMzNzY0NTY3Mzk2IiwiYXV0aF90aW1lIjoxNzA2MDE3MTMzLCJhbXIiOiJ7cHdkLCBtY2EsIG1mYSwgb3RwLCBzbXN9IiwiaXNzIjoiaHR0cHM6Ly9lZnMtc2Jib2wtaWZ0LXdlYi50ZXN0c2JpLnNiZXJiYW5rLnJ1Ojk0NDMvaWMiLCJleHAiOjE3MDYwMTc0NTQsImlhdCI6MTcwNjAxNzE1NCwibm9uY2UiOiI4MDAxMmM5Yy0xYjlhLTQ0OWUtYThkNS03NTEwMGVhNjk4YWMifQ.G5PoX66cDvkie6KqdRItbUmb_4QOHZl700gzXUMmldY7Po4Rk_Sw0jM3LNYN2s8NfDe6a1fTF70mR3zOpPFPiA

Заголовок. Алгоритм и тип токена:

{
  "typ": "JWT",
  "alg": "gost34.10-2012"
}

Полезная нагрузка:

{
  "sub": "6206285409fcc28cd1f96af880b5f9242bb6cde66e7dddfdfd3cde4c72372ed1",
  "aud": "92233764567396",
  "acr": "loa-3",
  "azp": "92233764567396",
  "auth_time": 1706017133,
  "amr": "{pwd, mca, mfa, otp, sms}",
  "iss": "https://efs-sbbol-ift-web.testsbi.sberbank.ru:9443/ic",
  "exp": 1706017454,
  "iat": 1706017154,
  "nonce": "80012c9c-1b9a-449e-a8d5-75100ea698ac",
  "header": {
    "typ": "JWT",
    "alg": "gost34.10-2012"
  }
}

Электронная подпись:

<Массив байт электронной подписи>

Обновление access_token, refresh_token

Cрок действия токена доступа (access_token) 60 минут. Поэтому требуется обновление токена доступа для последующих запросов в канале Sber API.

/ic/sso/api/v2/oauth/token

Запрос /v2/oauth/token позволяет получить новый токен доступа (access_token) и новый токен обновления (refresh_token).

Для использования запроса необходимо указать значение токена обновления (refresh_token), полученный при последней авторизации по СберБизнес ID или последнего обновления токена доступа.

Использованный токен обновления (refresh_token) переводится в статус резервного на 2 часа с момента выпуска новой пары ключей (access_token/refresh_token).

Если по каким-то причинам сформированная пара не была получена от Банка, то рекомендуется повторно отправить запрос на актуализацию ключей в течение 1 часа от момента отправки первой попытки, используя тот же refresh_token. Для последующих обновлений ключей доступа необходимо использовать refresh_token из новой пары ключей (access_token/refresh_token).