Bring Your Own Authentication (BYO Auth)

Use your existing authentication system and integrate Volr SDK seamlessly. BYO Auth allows you to mint a Volr session only when needed, deferring wallet creation until the user actually needs to make a payment.

Which method should I use?

Choose the integration method that best fits your existing authentication setup:

Quick Decision Guide

Do you have a backend server?

✅ Yes → Use Server Session Injection (recommended)
❌ No → Use OIDC Token Exchange

Are you using OIDC/JWT authentication?

✅ Yes → Use OIDC Token Exchange
❌ No → Use Server Session Injection

Comparison

Feature	Server Session Injection	OIDC Token Exchange
Security	High (server-side)	Medium (client-side exchange)
Implementation	Easy	Medium
Best for	Backend server available	Already using OIDC/JWT
Requires	Backend API endpoint	OIDC issuer configuration

Server Session Injection

Is this the right method for you?

✅ You have a backend server (Node.js, Python, etc.)
✅ You can make server-side API calls
✅ You want the highest security (server-side token creation)

How it works

Step-by-step guide

Follow these steps to integrate Server Session Injection. Check off each step as you complete it.

✅ Step 1: Generate Server Secret

Checklist:

Go to your project settings in the Volr Dashboard
Navigate to Settings > Authentication > BYO Auth
Select Server Session Injection
Click Generate Secret or Rotate Secret
Copy the secret immediately (it's shown only once)
Store it securely in your server environment variables (e.g., AWS Secrets Manager)

⚠️ Never expose the server secret to the client!

Code to store secret:

# Example: Store in environment variables
export VOLR_SERVER_SECRET=volr_ssk_...

✅ Step 2: Create backend endpoint

Create an endpoint in your backend that calls Volr API to create a session.

Node.js/Express
Next.js API Route
Python/FastAPI

app.post('/api/auth/volr-session', async (req, res) => {
  // Get authenticated user from your auth middleware
  const { userId, email, name } = req.user;

  const response = await fetch('https://api.volr.io/auth/external/session', {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.VOLR_API_KEY,
      'X-Volr-Server-Secret': process.env.VOLR_SERVER_SECRET,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      externalUserId: userId,
      email: email,
      name: name,
    }),
  });

  if (!response.ok) {
    return res.status(500).json({ error: 'Failed to create Volr session' });
  }

  const { accessToken, refreshToken } = await response.json();
  res.json({ accessToken, refreshToken });
});

// pages/api/auth/volr-session.ts (or app/api/auth/volr-session/route.ts)
import type { NextApiRequest, NextApiResponse } from 'next';

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  // Get authenticated user from your session/auth
  const user = await getAuthenticatedUser(req);
  if (!user) {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  try {
    const response = await fetch('https://api.volr.io/auth/external/session', {
      method: 'POST',
      headers: {
        'X-API-Key': process.env.VOLR_API_KEY!,
        'X-Volr-Server-Secret': process.env.VOLR_SERVER_SECRET!,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        externalUserId: user.id,
        email: user.email,
        name: user.name,
      }),
    });

    if (!response.ok) {
      const error = await response.text();
      return res.status(response.status).json({ error });
    }

    const { accessToken, refreshToken } = await response.json();
    res.json({ accessToken, refreshToken });
  } catch (error) {
    console.error('Volr session creation failed:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
}

from fastapi import FastAPI, Depends, HTTPException
import httpx
import os

app = FastAPI()

@app.post("/api/auth/volr-session")
async def create_volr_session(user: dict = Depends(get_authenticated_user)):
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "https://api.volr.io/auth/external/session",
            headers={
                "X-API-Key": os.getenv("VOLR_API_KEY"),
                "X-Volr-Server-Secret": os.getenv("VOLR_SERVER_SECRET"),
                "Content-Type": "application/json",
            },
            json={
                "externalUserId": user["id"],
                "email": user.get("email"),
                "name": user.get("name"),
            },
        )

        if response.status_code != 200:
            raise HTTPException(status_code=500, detail="Failed to create Volr session")

        data = response.json()
        return {"accessToken": data["accessToken"], "refreshToken": data["refreshToken"]}

✅ Step 3: Inject session in client

Checklist:

After user logs in with your existing auth, call your backend endpoint
Receive Volr tokens (accessToken, refreshToken) from backend
Call setSession() with the tokens
Verify that Volr SDK is ready

After your user logs in, call your backend endpoint and inject the Volr session.

React example:

import { useVolrSession } from '@volr/react';
import { useEffect } from 'react';

function App() {
  const { setSession } = useVolrSession();
  
  useEffect(() => {
    // After your existing login succeeds
    yourLoginFunction().then(async (user) => {
      // Get Volr session from your backend
      const res = await fetch('/api/auth/volr-session', {
        credentials: 'include', // Include your session cookie
      });
      
      if (!res.ok) {
        console.error('Failed to get Volr session');
        return;
      }
      
      const { accessToken, refreshToken } = await res.json();
      
      // Inject into Volr SDK
      await setSession({ accessToken, refreshToken });
      
      // Now Volr SDK is ready to use!
    });
  }, [setSession]);
}

✅ Step 4: Test the integration

Checklist:

User logs in with your existing auth system
Backend successfully creates Volr session
Client receives tokens and injects them
useVolr().isLoggedIn returns true
User can access wallet address via useVolr().evm.address
User can make payments (if payment flow is set up)

Verify that the session is properly injected and Volr SDK works correctly.

import { useVolr } from '@volr/react';

function TestComponent() {
  const { evm, isLoggedIn } = useVolr();
  
  if (!isLoggedIn) {
    return <div>Not logged in</div>;
  }
  
  return (
    <div>
      <p>Wallet address: {evm.address}</p>
      {/* Your Volr SDK is ready! */}
    </div>
  );
}

Complete code example

See the complete integration examples section below for full, working code examples.

Troubleshooting

Error: "Failed to create Volr session"

Check that your VOLR_API_KEY and VOLR_SERVER_SECRET are correctly set in your server environment
Verify that the externalUserId is being sent correctly
Check server logs for detailed error messages

Error: "Unauthorized"

Ensure your server secret hasn't expired (check rotation date in dashboard)
Verify the secret matches what's configured in the dashboard

Session not persisting

Make sure you're calling setSession after successful login
Check that tokens are being returned correctly from your backend endpoint

OIDC Token Exchange

Is this the right method for you?

✅ You're using OIDC/JWT-based authentication (Auth0, Okta, etc.)
✅ You can access ID tokens from your auth provider
✅ You want a simpler integration without backend changes

How it works

[User logs in with OIDC]
    ↓
[Get ID token]
    ↓
[Exchange with Volr]
    ↓
[Volr SDK ready!]

Step-by-step guide

Follow these steps to integrate OIDC Token Exchange. Check off each step as you complete it.

✅ Step 1: Configure OIDC settings

Checklist:

Go to your project settings in the Volr Dashboard
Navigate to Settings > Authentication > BYO Auth
Select OIDC Token Exchange
Enter your OIDC Issuer URL
Enter your JWKS URL
Enter your Audience (must match aud claim in ID token)
Click Save OIDC Settings

Configuration details:

OIDC Issuer: Your OIDC provider's issuer URL (e.g., https://your-domain.auth0.com/)
JWKS URL: URL where Volr can fetch your provider's public keys (e.g., https://your-domain.auth0.com/.well-known/jwks.json)
Audience: Must match the aud claim in your ID token

✅ Step 2: Get ID token from your auth provider

Checklist:

User logs in with your OIDC provider
Obtain the ID token from your auth provider
Verify token is valid and not expired

After user logs in with your OIDC provider, obtain the ID token.

// Example: After OIDC login
const idToken = await yourOidcProvider.getIdToken();

✅ Step 3: Exchange ID token for Volr session

Checklist:

Import useVolrSession hook
Call exchangeOidc(idToken) with the ID token
Handle success case (session created)
Handle error case (token validation failed)

Call exchangeOidc with the ID token to get Volr session tokens.

import { useVolrSession } from '@volr/react';
import { useEffect } from 'react';

function AfterOidcLogin({ idToken }) {
  const { exchangeOidc } = useVolrSession();
  
  useEffect(() => {
    exchangeOidc(idToken)
      .then((result) => {
        console.log('Volr session created:', result);
        // Volr SDK is now ready!
      })
      .catch((error) => {
        console.error('Failed to exchange token:', error);
      });
  }, [idToken, exchangeOidc]);
}

✅ Step 4: Test the integration

Checklist:

User logs in with OIDC provider
ID token is obtained successfully
Token exchange succeeds
useVolr().isLoggedIn returns true
User can access wallet address via useVolr().evm.address
User can make payments (if payment flow is set up)

Verify that the session is properly created and Volr SDK works.

import { useVolr } from '@volr/react';

function TestComponent() {
  const { evm, isLoggedIn } = useVolr();
  
  if (!isLoggedIn) {
    return <div>Not logged in</div>;
  }
  
  return (
    <div>
      <p>Wallet address: {evm.address}</p>
    </div>
  );
}

Complete code examples

React example:

import { VolrProvider, useVolrSession } from '@volr/react';
import { useEffect } from 'react';

function App() {
  return (
    <VolrProvider
      config={{
        projectApiKey: 'YOUR_PROJECT_API_KEY',
      }}
    >
      <OidcIntegration />
    </VolrProvider>
  );
}

function OidcIntegration() {
  const { exchangeOidc } = useVolrSession();
  
  useEffect(() => {
    // After your OIDC login succeeds
    const idToken = getOidcIdToken(); // Your OIDC provider function
    
    if (idToken) {
      exchangeOidc(idToken)
        .then((result) => {
          console.log('Volr session created:', result);
          // Session is now active, Volr SDK is ready
        })
        .catch((error) => {
          console.error('Token exchange failed:', error);
        });
    }
  }, [exchangeOidc]);
  
  return null;
}

Next.js example:

// app/layout.tsx or pages/_app.tsx
import { VolrProvider } from '@volr/react';
import { OidcSessionInjector } from './components/OidcSessionInjector';

export default function RootLayout({ children }) {
  return (
    <VolrProvider
      config={{
        projectApiKey: process.env.NEXT_PUBLIC_VOLR_API_KEY!,
      }}
    >
      <OidcSessionInjector />
      {children}
    </VolrProvider>
  );
}

// components/OidcSessionInjector.tsx
'use client';

import { useVolrSession } from '@volr/react';
import { useEffect } from 'react';

export function OidcSessionInjector() {
  const { exchangeOidc } = useVolrSession();
  
  useEffect(() => {
    // Get ID token from your OIDC provider (e.g., Auth0, Okta, etc.)
    const idToken = getOidcIdToken();
    
    if (idToken) {
      exchangeOidc(idToken)
        .then((result) => {
          console.log('Volr session created');
        })
        .catch((error) => {
          console.error('Failed to exchange token:', error);
        });
    }
  }, [exchangeOidc]);
  
  return null;
}

Security tip

For stricter security, exchange tokens on your server and then call setSession on the client. This keeps the token exchange logic server-side.

Troubleshooting

Error: "Invalid token"

Verify your OIDC issuer, JWKS URL, and audience are correctly configured
Check that the ID token's aud claim matches your configured audience
Ensure the token hasn't expired

Error: "Token validation failed"

Check that your JWKS URL is accessible and returns valid keys
Verify the token signature matches your provider's keys

Session not persisting

Make sure you're calling exchangeOidc after successful OIDC login
Check that the ID token is valid and not expired

Complete code examples

Server Session Injection - Full Example

Backend (Node.js/Express):

const express = require('express');
const app = express();

app.use(express.json());

// Your existing auth middleware
const authenticateUser = (req, res, next) => {
  // Your authentication logic here
  req.user = { userId: 'user123', email: 'user@example.com', name: 'John Doe' };
  next();
};

// Volr session endpoint
app.post('/api/auth/volr-session', authenticateUser, async (req, res) => {
  const { userId, email, name } = req.user;
  
  try {
    const response = await fetch('https://api.volr.io/auth/external/session', {
      method: 'POST',
      headers: {
        'X-API-Key': process.env.VOLR_API_KEY,
        'X-Volr-Server-Secret': process.env.VOLR_SERVER_SECRET,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        externalUserId: userId,
        email: email,
        name: name,
      }),
    });
    
    if (!response.ok) {
      const error = await response.text();
      return res.status(response.status).json({ error });
    }
    
    const { accessToken, refreshToken } = await response.json();
    res.json({ accessToken, refreshToken });
  } catch (error) {
    console.error('Volr session creation failed:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

app.listen(3000);

Client (React):

import { VolrProvider, useVolrSession } from '@volr/react';
import { useEffect } from 'react';

function App() {
  return (
    <VolrProvider
      config={{
        projectApiKey: process.env.REACT_APP_VOLR_API_KEY!,
      }}
    >
      <SessionInjector />
      {/* Your app components */}
    </VolrProvider>
  );
}

function SessionInjector() {
  const { setSession } = useVolrSession();
  
  useEffect(() => {
    // After your login succeeds
    if (isLoggedIn()) {
      fetch('/api/auth/volr-session', {
        credentials: 'include',
      })
        .then((res) => res.json())
        .then(({ accessToken, refreshToken }) => {
          setSession({ accessToken, refreshToken });
        })
        .catch(console.error);
    }
  }, [setSession]);
  
  return null;
}

Next steps

After successfully integrating BYO Auth:

Test wallet creation: Verify that wallets are created when users first make a payment
Configure payment flows: Set up your payment integration using the Volr SDK
Monitor usage: Check your dashboard for authentication and wallet creation metrics

For more information, see:

Which method should I use?​

Quick Decision Guide​

Comparison​

Server Session Injection​

Is this the right method for you?​

How it works​

Step-by-step guide​

✅ Step 1: Generate Server Secret​

✅ Step 2: Create backend endpoint​

✅ Step 3: Inject session in client​

✅ Step 4: Test the integration​

Complete code example​

Troubleshooting​

OIDC Token Exchange​

Is this the right method for you?​

How it works​

Step-by-step guide​

✅ Step 1: Configure OIDC settings​

✅ Step 2: Get ID token from your auth provider​

✅ Step 3: Exchange ID token for Volr session​

✅ Step 4: Test the integration​

Complete code examples​

Security tip​

Troubleshooting​

Complete code examples​

Server Session Injection - Full Example​

Next steps​

Which method should I use?

Quick Decision Guide

Comparison

Server Session Injection

Is this the right method for you?

How it works

Step-by-step guide

✅ Step 1: Generate Server Secret

✅ Step 2: Create backend endpoint

✅ Step 3: Inject session in client

✅ Step 4: Test the integration

Complete code example

Troubleshooting

OIDC Token Exchange

Is this the right method for you?

How it works

Step-by-step guide

✅ Step 1: Configure OIDC settings

✅ Step 2: Get ID token from your auth provider

✅ Step 3: Exchange ID token for Volr session

✅ Step 4: Test the integration

Complete code examples

Security tip

Troubleshooting

Complete code examples

Server Session Injection - Full Example

Next steps