One-time tokens

A one-time token is a JWT signed with your client secret, so your application can verify it on its own without calling Bito. It is what Bito appends to your widget's iframe URL, and it is the right tool whenever Bito has to hand a browser something your backend must trust.

Minting one

Requires a logged-in Bito user session — not an integration token. The integration must be installed in that account, otherwise the call is refused with Integration is not installed.

Request

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

{
    "client_id": "69c50a2d50f7b939923a469b"
}

Response

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

Claims

Claim	Description
iss	Issuer: https://{subdomain}.{domain}
aud	Audience: your client's redirect_uri
jti	Unique token id (UUID)
nbf	Not-before timestamp
account_id	The merchant account
user_id	The Bito user who opened your app
subdomain	The account's subdomain
client_id	Your OAuth client id
exp	Expiry, 24 hours after issue

Verifying

The token is signed HS256 with your client secret. Verify it before trusting anything in it.

import jwt from 'jsonwebtoken';

export function verifyOneTimeToken(token, secret, clientId) {
    // Throws on a bad signature, a expired token, or one issued before `nbf`.
    const claims = jwt.verify(token, secret, { algorithms: ['HS256'] });

    if (claims.client_id !== clientId) throw new Error('token belongs to another client');

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

WARNING

Do not decode without verifying. jwt.decode reads the claims of any string the browser hands you; only jwt.verify proves Bito issued it.

TIP

jti is unique per token — store the ones you have seen if you want single-use semantics enforced on your side. Bito does not track redemption.

See Widget (iframe app) for the receiving side end to end.