Одноразовые токены

Одноразовый токен — это JWT, подписанный секретом вашего клиента, поэтому ваше приложение может проверить его самостоятельно, без обращения к Bito. Именно его Bito добавляет к URL вашего iframe-виджета, и он же нужен везде, где Bito передаёт браузеру данные, которым должен доверять ваш сервер.

Получение токена

Требуется сессия вошедшего пользователя Bito — не токен интеграции. Интеграция должна быть установлена в этом аккаунте, иначе запрос отклоняется с Integration is not installed.

Запрос

POST /auth/get-one-time-token
Authorization: Bearer <user_session_token>
Content-Type: application/json

{
    "client_id": "69c50a2d50f7b939923a469b"
}

Ответ

{
    "code": 0,
    "message": "Success",
    "data": "eyJhbGciOiJIUzI1NiIs..."
}

Поля токена

Поле	Описание
iss	Издатель: https://{subdomain}.{domain}
aud	Получатель: redirect_uri вашего клиента
jti	Уникальный идентификатор токена (UUID)
nbf	Время, раньше которого токен недействителен
account_id	Аккаунт клиента
user_id	Пользователь Bito, открывший ваше приложение
subdomain	Поддомен аккаунта
client_id	Ваш OAuth client id
exp	Истекает через 24 часа после выдачи

Проверка

Токен подписан алгоритмом HS256 секретом вашего клиента. Проверьте подпись, прежде чем доверять содержимому.

import jwt from 'jsonwebtoken';

export function verifyOneTimeToken(token, secret, clientId) {
    // Бросает исключение при неверной подписи, истёкшем токене или токене «из будущего».
    const claims = jwt.verify(token, secret, { algorithms: ['HS256'] });

    if (claims.client_id !== clientId) throw new Error('токен принадлежит другому клиенту');

    return { accountId: claims.account_id, userId: claims.user_id };
}

WARNING

Не декодируйте токен без проверки подписи. jwt.decode прочитает любую строку из браузера; только jwt.verify доказывает, что токен выдал Bito.

TIP

jti уникален для каждого токена — сохраняйте увиденные значения, если хотите строго одноразовое использование. Bito сам факт использования не отслеживает.

Принимающая сторона целиком описана в разделе Виджет (iframe-приложение).