TokenPass

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-auth

Server 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 host parameter matches your domain
  • Set appropriate token expiry times

On this page