Skip to main content

​
createSessionToken

Create a session token to authenticate a customer with the React SDK. 
const { sessionToken, expiresAt } = await billing.createSessionToken({
  externalUserId: "user_123",
  email: "user@example.com", // recommended
  expiresIn: 3600,
});

​
Parameters

NameTypeRequiredDescription
externalUserIdstringYesYour user’s unique ID from your database
emailstringNo, but recommendedYour user’s email. Lets BillingOS lazy-bind imported Stripe customers on first session. See Migrating from Stripe.
externalOrganizationIdstringNoOrganization ID for B2B scenarios
expiresInnumberNoToken lifetime in seconds (60–86400, default: 3600)
allowedOperationsstring[]NoScope the token to specific operations
metadataRecord<string, any>NoAdditional metadata (IP, user agent, etc.)

​
Response

{
  sessionToken: "bos_session_test_abc123...",
  expiresAt: Date,        // Token expiration timestamp
  unresolvedCustomers?: number  // Count of imported customers still awaiting bind
}
The unresolvedCustomers field is populated when you have imported customers from Stripe that haven’t been bound yet. The SDK uses it to surface a one-time console.warn if you’re issuing tokens without email.

​
revokeSessionToken

Revoke a previously created session token. 
await billing.revokeSessionToken("token_id_here");

​
Token format

Session tokens are prefixed based on your API key environment:
API keyToken prefixRoutes to
sk_test_*bos_session_test_*Sandbox API
sk_live_*bos_session_live_*Production API
The React SDK reads this prefix and routes requests to the correct API automatically.

​
Next.js example

app/api/billingos-session/route.ts
import { BillingOS } from "@billingos/node";
import { getServerSession } from "next-auth";

const billing = new BillingOS({
  secretKey: process.env.BILLINGOS_SECRET_KEY!,
});

export async function GET() {
  const session = await getServerSession();

  if (!session?.user?.id) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { sessionToken, expiresAt } = await billing.createSessionToken({
    externalUserId: session.user.id,
    email: session.user.email, // recommended
    expiresIn: 3600,
  });

  return Response.json({ sessionToken, expiresAt });
}

​
Security notes

  • Tokens are short-lived (default: 1 hour)
  • Each token is scoped to a single customer
  • Tokens are verified on every API call
  • Expired tokens are automatically rejected
  • Always authenticate the user before creating a token