Авторизация

Для авторизации в API используется JWT-формат. Авторизационный токен состоит из трех частей:

1. header — JSON. Содержит информацию о том, как должна вычисляться JWT-подпись.
2. payload — JSON. Содержит полезную информацию о токене.
3. signature — HS256-подпись.

• Пример авторизации на Python
• Shell-скрипт для генерации JWT

Создание токена

1. Зарегистрируйтесь в Т-Банк Software и получите API_KEY и SECRET_KEY.

2. Создайте объект header. В поле kid укажите API_KEY, остальные поля заполните по образцу:

   {
    "alg": "HS256",
    "typ": "JWT",
    "kid": "API_KEY"
   }

3. Создайте объект payload.

   • iss — строка, идентифицирующая систему, которая выпустила токен;
   • sub — строка, идентифицирующая конечного пользователя;
   • aud — сервис или набор сервисов, для которых предназначается токен;
   • exp — время, после которого токен будет недействительным (Unix time);
   • iat — время выпуска токена (Unix time);
   • nbf — время начала действия токена (Unix time);
   • jti — уникальный идентификатор токена;
   • sid — ID сессии пользователя, для которого был выпущен токен.

   Пример объекта payload:

   {
     "iss": "mobile_bank_api",
     "sub": "user12345",
     "aud": "tinkoff.cloud.stt",
     "exp": 1609459199,
     "iat": 1542362238,
     "nbf": 1542362238,
     "jti": "123e4567-e89b-12d3-a456-426655440000",
     "sid": "123e4567-e89b-12d3-a456-426655440000"
   }

4. Вычислите signature. Пример вычисления на Python:

    SECRET_KEY = 'Y1v7D9ic34GedKJV9Sb/i9O23U/Aq644TWeCA4nuYBs='
    unsignedToken = base64.urlsafe_b64encode(header).strip(b'=') + b'.' + base64.urlsafe_b64encode(payload).strip(b'='))
    signature = hmac.new(base64.urlsafe_b64decode(SECRET_KEY), msg=unsignedToken, digestmod="sha256").digest()

5. Получите токен, совмещая все компоненты.

   token = unsignedToken + b'.' + base64.urlsafe_b64encode(signature).strip(b'=')

6. Провалидируйте полученный токен. Пример валидатора.

7. Передавайте валидный токен в каждом запросе в поле Authorization:

    GET /v1/stt:recognize HTTP/1.1
    Host: api.tinkoff.ai
    Content-Type: application/json
    Authorization: Bearer <TOKEN>

Хранение ключей

Чтобы предотвратить утечку токена, рекомендуем хранить API_KEY и SECRET_KEY в отдельном сервисе. Клиенты должны обращаться к этому сервису для получения и обновления токена.

SECRET_KEY должен храниться только в одном сервисе.

Пример:

1. Есть мобильное приложение (клиент) и backend (сервер).
2. Сервер отвечает за хранение API_KEY, SECRET_KEY и генерацию токена.
3. Клиент получает от сервера токен и при необходимости обновляет его, отправляя соответствующий запрос на сервер.
4. Клиент использует токен для авторизации в сервисах VoiceKit и не знает SECRET_KEY.