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 — Required expected aud claim in your JWTs. Only tokens with a matching audience are accepted.
Issuer — Required expected iss claim in your JWTs. 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
Include an exp claim and be valid (not expired)
Match the configured aud and iss

Client-Side Integration

1. Configure Privacy Boost for Direct IdP Auth

Browser IdP callbacks are only supported in local key-vault mode. The default browser mode is the isolated iframe vault, which intentionally does not accept host-page token callbacks.

import { PrivacyBoost } from '@sunnyside-io/privacy-boost';

const sdk = new PrivacyBoost({
  serverUrl: 'https://optimism.sepolia.privacyboost.io',
  appId: 'app_abc123xyz',
  keyVault: { mode: 'local' },
});

2. Provide the External JWT

For browser apps, pass getExternalToken. It returns the raw JWT from Auth0, Firebase, Supabase, Clerk, or your own auth system. The SDK attaches it to both Privacy Boost auth requests.

const getExternalToken = async () => {
  const token = await getYourAuthToken();
  if (!token) throw new Error('Not logged in');
  return token;
};

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

Optional: Backend Token Provider

Use tokenProvider instead when your backend must perform the Privacy Boost token exchange itself. Do not pass both tokenProvider and getExternalToken.

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 }
};

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

class CustomJWTTokenProvider: TokenProvider {
    func getToken(loginPayloadJson: String) async throws -> TokenResponse {
        let yourAuthToken = try await getYourAuthToken()

        var request = URLRequest(url: URL(string: "https://your-backend.com/api/privacy-boost/auth")!)
        request.httpMethod = "POST"
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
        request.setValue("Bearer \(yourAuthToken)", forHTTPHeaderField: "Authorization")
        request.httpBody = loginPayloadJson.data(using: .utf8)

        let (data, _) = try await URLSession.shared.data(for: request)
        let json = try JSONSerialization.jsonObject(with: data) as! [String: Any]
        return TokenResponse(
            token: json["token"] as! String,
            expiresIn: json["expiresIn"] as! UInt64
        )
    }
}

class CustomJWTTokenProvider : TokenProvider {
    override suspend fun getToken(loginPayloadJson: String): TokenResponse {
        val yourAuthToken = getYourAuthToken()

        val response = httpClient.post("https://your-backend.com/api/privacy-boost/auth") {
            contentType(ContentType.Application.Json)
            header("Authorization", "Bearer $yourAuthToken")
            setBody(loginPayloadJson)
        }
        val json = Json.parseToJsonElement(response.bodyAsText()).jsonObject
        return TokenResponse(
            token = json["token"]!!.jsonPrimitive.content,
            expiresIn = json["expiresIn"]!!.jsonPrimitive.long.toULong()
        )
    }
}

3. Pass Native Token Providers to authenticate()

try await sdk.authenticate(
    wallet: walletDelegate,
    tokenProvider: CustomJWTTokenProvider()
)

sdk.authenticate(
    wallet = walletDelegate,
    tokenProvider = CustomJWTTokenProvider()
)

4. Implement the Backend Endpoint

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

// Express.js example
function toPrivacyBoostAuthPayload(payload: any) {
  return {
    grant_type: payload.grantType,
    app_id: payload.appId,
    client_id: payload.clientId,
    client_secret: payload.clientSecret,
    mpk: payload.mpk,
    viewauth_signature: payload.viewauthSignature,
    nonce: payload.nonce,
    account_id: payload.accountId,
    account_salt: payload.accountSalt,
    viewing_public_key: payload.viewingPublicKey,
    nullifying_key: payload.nullifyingKey,
    wallet_address: payload.walletAddress,
    auth_pk_x: payload.authPkX,
    auth_pk_y: payload.authPkY,
    auth_expiry: payload.authExpiry,
    auth_signature: payload.authSignature,
  };
}

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://optimism.sepolia.privacyboost.io/auth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      ...toPrivacyBoostAuthPayload(req.body), // SDK camelCase payload -> /auth/token wire payload
      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

Quickstart

Setup

SDKs

Custom JWT Integration

Custom JWT Integration

How It Works

Server-Side Setup

JWT Requirements

Client-Side Integration

1. Configure Privacy Boost for Direct IdP Auth

2. Provide the External JWT

Optional: Backend Token Provider

3. Pass Native Token Providers to authenticate()

4. Implement the Backend Endpoint

Testing

Next Steps

​Custom JWT Integration

​How It Works

​Server-Side Setup

​JWT Requirements

​Client-Side Integration

​1. Configure Privacy Boost for Direct IdP Auth

​2. Provide the External JWT

​Optional: Backend Token Provider

​3. Pass Native Token Providers to authenticate()

​4. Implement the Backend Endpoint

​Testing

​Next Steps

Custom JWT Integration

How It Works

Server-Side Setup

JWT Requirements

Client-Side Integration

1. Configure Privacy Boost for Direct IdP Auth

2. Provide the External JWT

Optional: Backend Token Provider

3. Pass Native Token Providers to authenticate()

4. Implement the Backend Endpoint

Testing

Next Steps