Авторизация запросов
При работе со SberJazz API вам понадобятся токены двух видов: транспортный токен и токен доступа.
Создание транспортного токена
Транспортный токен — это JSON Web Token (JWT), подписанный с помощью ключа SDK по алгоритму ECDSA.
Полезная нагрузка транспортного токена включает обязательные поля:
- Описание
- Пример
Вы можете передавать в полезной нагрузке различные необязательные поля вроде имени пользователя, адреса электронной почты и других.
С помощью одного транспортного токена вы можете выпустить неограниченного количество токенов доступа с различными параметрами (сроком действия, идентификатором, данными пользователя и другими).
Для создания транспортного токена:
- Выпустите ключ SberJazz SDK.
- Добавьте логику, с помощью которой приложение будет генерировать транспортный токен в соответствии с форматом JWT.
- Зашифруйте данные по алгоритму AES256 и подпишите их с помощью ключа SberJazz SDK по алгоритму ECDSA.
Пример создания транспортного токена в SberJazz SDK для Web
Вы можете создать транспортный токен с помощью утилиты SberJazz SDK для Web.
Для создания транспортного токена:
Выпустите ключ SberJazz SDK.
Декодируйте ключ из base64 в
object.export function parseSecret(key: Base64String): SecretResult {
let result: SecretResult;
try {
result = JSON.parse(decoder.decode(decodeSafeUrl(key)));
} catch (error) {
throw createError('ER_INVALID_KEY', 'Invalid Key');
}
if (!isMatching(SECRET_RESULT_PATTERN, result)) {
throw createError('ER_INVALID_KEY', 'Invalid Key');
}
return result;
}Получите детали алгоритма создания приватного ключа.
const algorithm = recognizeAlgorithm(secret);Сформируйте полезную нагрузку JWT.
const payload: JWTPayload = {
iat,
exp: iat + expireIn,
jti: requestId,
sdkProjectId: algorithm.projectId,
iss, // Для логов. Не больше 100 символов.
sub, // Идентификатор пользователя в бэкенде приложения
userName: userName, // Необязательно. Используется для отображения в комнате
userEmail: userEmail, // Необязательно
};Сформируйте заголовок JWT.
const header: JWTHeader = {
alg: algorithm.alg,
kid: algorithm.kid,
typ: 'JWT',
};Сформируйте первую часть JWT из заголовка и полезной нагрузки.
const textToSign = headerBase64 + '.' + payloadBase64;Выпустите приватный ключ с помощью алгоритма криптографии ECDSA.
const privateKey = await importECDSAPrivateKey(algorithm.jwk);Подпишите первую часть JWT с помощью приватного ключа.
const { signature } = await algorithm.sign(textToSign, privateKey);Сформируйте итоговый транспортный токен.
const signedJwt = createSignedJWT(textToSign, signature);
Используйте транспортный токен для получения токена доступа.
Создание тестового транспортного токена
С помощью формы вы можете создать тестовый транспортный токен. Токен действует в течение 30 минут. Для создания тестового токена потребуется ключ SberJazz SDK.
В целях безопасности для создания текстового токена используйте отдельный ключ SDK, который не будет применяться в эксплуатационной среде.
для тестирования запросов
Получение токена доступа
Токен доступа нужен для авторизации запросов к SberJazz API.
Для получения токена доступа передайте запрос -запрос по адресу POST /v1/auth/login:
curl -L -X POST 'https://api.jazz.sber.ru/v1/auth/login' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <транспортный_токен>'
В ответ вы получите строку с токеном доступа:
- Пример
- Описание
Авторизация запросов
Используйте токен доступа для авторизации запросов к SberJazz API, например, для создания комнаты (запрос POST /room/create):
curl -L -X POST 'https://api.jazz.sber.ru/v1/room/create' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <токен_доступа>' \
--data-raw '{
"roomTitle": "Мастер-класс"
}'