Server-to-Server Authentication

The api_secret auth method is designed for server-to-server integrations where your backend controls the authentication flow. Instead of relying on a third-party auth provider, your backend authenticates directly with the Privacy Boost API using a client_id and client_secret pair — similar to OAuth 2.0 client credentials. This is the right choice when:

Your backend already manages user authentication and you don’t use a third-party auth provider
You need programmatic access (scripts, bots, automated systems)
You want full control over who can authenticate without depending on an external JWKS endpoint

How It Works

Setup

1. Get API Credentials

Contact the Privacy Boost team to configure your app with the api_secret auth method. You’ll receive:

App ID — Your application identifier (e.g., app_abc123xyz)
Client ID — A unique identifier for your credentials (e.g., pb_cred_abc123xyz...)
Client Secret — A secret key for authenticating requests

Store your client_secret securely. It should never be exposed in client-side code, committed to version control, or logged. Use environment variables or a secrets manager.

2. Store Credentials Securely

# Environment variables (development)
export PB_CLIENT_ID="pb_cred_abc123xyz..."
export PB_CLIENT_SECRET="your-secret-here"

# Or use a secrets manager in production (AWS Secrets Manager, HashiCorp Vault, etc.)

Client-Side Integration

If this runs in a browser, set keyVault.mode to local before passing a tokenProvider; the default browser iframe vault 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' },
});

Implement a Token Provider

Your token provider routes the SDK’s login payload through your backend:

const tokenProvider = async (loginPayload: any) => {
  const res = await fetch('https://your-backend.com/api/privacy-boost/auth', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${yourSessionToken}`, // Your own auth
    },
    body: JSON.stringify(loginPayload),
  });

  if (!res.ok) throw new Error('Auth failed');
  return await res.json(); // { token, expiresIn }
};

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

class APISecretTokenProvider: TokenProvider {
    func getToken(loginPayloadJson: String) async throws -> TokenResponse {
        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 \(yourSessionToken)", 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
        )
    }
}

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

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

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

Backend Endpoint

Your backend endpoint receives the SDK’s login payload, adds your API credentials, 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 user auth (session, JWT, etc.)
  const user = await verifyYourAuth(req.headers.authorization);
  if (!user) return res.status(401).json({ error: 'Unauthorized' });

  // 2. Forward to Privacy Boost with API credentials
  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
        client_id: process.env.PB_CLIENT_ID,  // Your API credential ID
        client_secret: process.env.PB_CLIENT_SECRET, // Your API secret
      }),
    }
  );

  if (!pbResponse.ok) {
    const err = await pbResponse.json();
    return res.status(pbResponse.status).json(err);
  }

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

# FastAPI example
def to_privacy_boost_auth_payload(payload: dict) -> dict:
    wire = {
        "grant_type": payload.get("grantType"),
        "app_id": payload.get("appId"),
        "client_id": payload.get("clientId"),
        "client_secret": payload.get("clientSecret"),
        "mpk": payload.get("mpk"),
        "viewauth_signature": payload.get("viewauthSignature"),
        "nonce": payload.get("nonce"),
        "account_id": payload.get("accountId"),
        "account_salt": payload.get("accountSalt"),
        "viewing_public_key": payload.get("viewingPublicKey"),
        "nullifying_key": payload.get("nullifyingKey"),
        "wallet_address": payload.get("walletAddress"),
        "auth_pk_x": payload.get("authPkX"),
        "auth_pk_y": payload.get("authPkY"),
        "auth_expiry": payload.get("authExpiry"),
        "auth_signature": payload.get("authSignature"),
    }
    return {key: value for key, value in wire.items() if value is not None}

@app.post("/api/privacy-boost/auth")
async def privacy_boost_auth(request: Request):
    # 1. Verify your own user auth
    user = await verify_your_auth(request.headers.get("authorization"))
    if not user:
        raise HTTPException(status_code=401)

    # 2. Forward to Privacy Boost with API credentials
    payload = to_privacy_boost_auth_payload(await request.json())
    payload["client_id"] = os.environ["PB_CLIENT_ID"]
    payload["client_secret"] = os.environ["PB_CLIENT_SECRET"]

    async with httpx.AsyncClient() as client:
        pb_response = await client.post(
            "https://optimism.sepolia.privacyboost.io/auth/token",
            json=payload,
        )

    data = pb_response.json()
    return {"token": data["access_token"], "expiresIn": data["expires_in"]}

Credential Management

Rotation

API credentials can be rotated without downtime:

Request a new credential from the Privacy Boost team
Update your backend to use the new client_id and client_secret
Revoke the old credential

Expiry

Credentials can optionally have an expiry date. If your credential expires, requests will fail with invalid_credentials. Request a new credential before the current one expires.

Security Best Practices

Never expose credentials in client-side code. The client_id and client_secret must only exist on your backend.
Use environment variables or a secrets manager. Don’t hardcode credentials.
Rotate credentials periodically. Treat them like passwords.
Authenticate your own users first. Your backend endpoint should verify the caller’s identity (session token, JWT, etc.) before forwarding to Privacy Boost. Otherwise, anyone who discovers your endpoint can authenticate.
Use HTTPS only. All communication between your backend and Privacy Boost must be over HTTPS.

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:

Custom JWT — For Auth0, Firebase, Supabase, Clerk, or OIDC providers
Privy — For Privy social login and embedded wallets

Quickstart

Setup

SDKs

Server-to-Server Authentication

Server-to-Server Authentication

How It Works

Setup

1. Get API Credentials

2. Store Credentials Securely

Client-Side Integration

Implement a Token Provider

Backend Endpoint

Credential Management

Rotation

Expiry

Security Best Practices

Next Steps

​Server-to-Server Authentication

​How It Works

​Setup

​1. Get API Credentials

​2. Store Credentials Securely

​Client-Side Integration

​Implement a Token Provider

​Backend Endpoint

​Credential Management

​Rotation

​Expiry

​Security Best Practices

​Next Steps

Server-to-Server Authentication

How It Works

Setup

1. Get API Credentials

2. Store Credentials Securely

Client-Side Integration

Implement a Token Provider

Backend Endpoint

Credential Management

Rotation

Expiry

Security Best Practices

Next Steps