Custom JWT Integration

Authenticate Privacy Boost users with your own auth system using custom JWTs

Custom JWT Integration

If you already have an authentication system that issues JWTs (Auth0, Firebase Auth, Supabase Auth, Clerk, or a custom backend), you can use the custom_jwt auth method to connect it to Privacy Boost. Your backend validates the user’s identity with your auth provider and forwards a JWT to Privacy Boost, which verifies it via your JWKS endpoint.

How It Works

Server-Side Setup

Your app must be configured with the custom_jwt auth method. Contact the Privacy Boost team with:

• JWKS URL — The HTTPS endpoint serving your JSON Web Key Set (e.g., https://your-auth.com/.well-known/jwks.json). Privacy Boost fetches this to verify JWT signatures.
• Audience (optional) — Expected aud claim in your JWTs. If set, only tokens with a matching audience are accepted.
• Issuer (optional) — Expected iss claim in your JWTs. If set, only tokens with a matching issuer are accepted.

The backend configuration looks like:

{
  "jwks_url": "https://your-auth.com/.well-known/jwks.json",
  "audience": "your-app-id",
  "issuer": "https://your-auth.com"
}

JWT Requirements

Your JWT must:

• Be signed with RS256, RS384, RS512, ES256, ES384, or ES512
• Include a kid (Key ID) header matching a key in your JWKS
• Include a sub or user_id claim identifying the user
• Match the configured aud and iss (if set)
• Be valid (not expired)

Client-Side Integration

1. Implement a Token Provider

Your token provider routes the SDK’s login payload through your backend, which attaches the custom JWT:

TypeScript

const tokenProvider = async (loginPayload: any) => {
  // Get your auth token (from your auth system)
  const yourAuthToken = await getYourAuthToken();

  // Send both to your backend
  const res = await fetch('https://your-backend.com/api/privacy-boost/auth', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${yourAuthToken}`,
    },
    body: JSON.stringify(loginPayload),
  });

  return await res.json(); // { token, expiresIn }
};

2. Pass the Token Provider to authenticate()

TypeScript

await sdk.auth.authenticate(adapter, {
  type: 'walletDerived',
  tokenProvider,
});

3. Implement the Backend Endpoint

Your backend endpoint receives the SDK’s login payload, attaches your JWT, and forwards to Privacy Boost:

// Express.js example
app.post('/api/privacy-boost/auth', async (req, res) => {
  // 1. Verify your own auth (e.g., check the Authorization header)
  const user = await verifyYourAuth(req.headers.authorization);
  if (!user) return res.status(401).json({ error: 'Unauthorized' });

  // 2. Get a JWT for this user from your auth system
  const customJWT = await issueJWTForUser(user.id);

  // 3. Forward to Privacy Boost with the custom JWT attached
  const pbResponse = await fetch('https://test-api.privacy-boost.sunnyside.io/indexer/auth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      ...req.body,            // SDK's login payload (mpk, viewauth_signature, nonce, etc.)
      custom_jwt_token: customJWT,  // Your JWT
    }),
  });

  const data = await pbResponse.json();
  res.json({
    token: data.access_token,
    expiresIn: data.expires_in,
  });
});

Testing

For development, you can use app_id_only to skip the token provider entirely. Switch to custom_jwt when moving to production.

Next Steps

Continue with setup:

• Key Management — Configure key persistence for returning users
• Error Handling — Handle auth and operation errors

Or explore other auth methods:

• Privy — For Privy social login and embedded wallets
• Dynamic — For Dynamic wallet connection and embedded wallets
• API Secret — For server-to-server with client credentials