Integration Guide
Integrate TokenPass authentication into your application
Integration Guide
This guide shows how to integrate TokenPass into your application.
Using Better Auth Plugin
The easiest way to integrate TokenPass is with the Better Auth plugin:
bun add @sigma-auth/better-auth-plugin better-authServer Setup
import { betterAuth } from "better-auth";
import { sigmaAuth } from "@sigma-auth/better-auth-plugin";
export const auth = betterAuth({
plugins: [
sigmaAuth({
tokenpassUrl: "http://localhost:21000"
})
]
});Client Setup
import { createAuthClient } from "better-auth/client";
import { sigmaAuthClient } from "@sigma-auth/better-auth-plugin/client";
export const authClient = createAuthClient({
plugins: [sigmaAuthClient()]
});
// Sign in with TokenPass
await authClient.signIn.sigma();Direct API Integration
If you prefer direct integration:
1. Request Authentication
// Redirect user to TokenPass
const params = new URLSearchParams({
redirect: 'https://yourapp.com/callback',
host: 'yourapp.com',
scopes: 'sign'
});
window.location.href = `http://localhost:21000/auth?${params}`;2. Handle Callback
// On your callback page
const url = new URL(window.location.href);
const signature = url.searchParams.get('signature');
const address = url.searchParams.get('address');
const message = url.searchParams.get('message');
// Verify the signature on your server
const verified = await verifySignature({ signature, address, message });3. Verify Signature
Use the bsv library to verify:
import { BSM } from '@bsv/sdk';
function verifySignature({ signature, address, message }) {
return BSM.verify(message, signature, address);
}React Hook Example
import { useState } from 'react';
export function useTokenPass() {
const [user, setUser] = useState(null);
const signIn = () => {
const params = new URLSearchParams({
redirect: window.location.origin + '/auth/callback',
host: window.location.host,
scopes: 'sign'
});
window.location.href = `http://localhost:21000/auth?${params}`;
};
const handleCallback = async (searchParams) => {
const signature = searchParams.get('signature');
const address = searchParams.get('address');
// Verify with your backend
const res = await fetch('/api/auth/verify', {
method: 'POST',
body: JSON.stringify({ signature, address })
});
if (res.ok) {
setUser(await res.json());
}
};
return { user, signIn, handleCallback };
}Security Considerations
- Always verify signatures on your server, not the client
- Use HTTPS in production
- Validate the
hostparameter matches your domain - Set appropriate token expiry times