toni™
Sign In
Get Verified
Documentation

Toni API Reference

The Toni API is organized around REST. Follow this step-by-step guide to get Toni identity verification fully integrated into your application in under 10 minutes.

1

Add the Verification Button (Frontend)

Create a simple button in your app that triggers a request to your backend. When the user clicks this, you'll generate a secure Toni session and redirect them to it.

components/VerifyButton.tsx
export default function VerifyButton() {
  const handleVerify = async () => {
    // Call your own backend to securely initialize Toni
    const res = await fetch('/api/verify-init', { method: 'POST' });
    const { sessionUrl } = await res.json();
    
    // Redirect the user to the secure Toni interface
    window.location.href = sessionUrl;
  };

  return (
    <button onClick={handleVerify} className="btn-primary">
      Verify with Toni
    </button>
  );
}
2

Initialize the Session (Backend)

On your server, use your API Keys to securely request a session URL from the Toni API. Do not expose your Secret Key on the frontend.

app/api/verify-init/route.ts
export async function POST(req) {
  // Pass your credentials to the Toni API
  const response = await fetch('https://api.vbtoni.com/v1/sessions', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.TONI_SECRET_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      userId: 'user_123', // Your internal user ID
      redirectUrl: 'https://your-app.com/dashboard'
    })
  });

  const session = await response.json();
  return Response.json({ sessionUrl: session.url });
}
3

Listen for Webhooks

Once the user completes verification, Toni will instantly send a webhook to your server so you can update your database.

app/api/webhooks/toni/route.ts
export async function POST(req) {
  const event = await req.json();

  if (event.type === 'verification.completed') {
    const userId = event.data.userId;
    const isVerified = event.data.verified;

    // Update your database
    await db.user.update({
      where: { id: userId },
      data: { isVerified: isVerified }
    });
  }

  return Response.json({ received: true });
}

Authentication

The Toni API uses API keys to authenticate requests. You can view and manage your API keys in the Toni Dashboard.

cURL Example
curl https://api.vbtoni.com/v1/users \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc:

Keep your keys secure

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Test Keys

Toni does not use a separate sandbox server. Instead, we use Test Keys to safely test your integration without affecting live data. Use your test API keys (prefixed with sk_test_) to interact with the API in Test Mode. The Toni API will automatically return mock data and bypass real verification flows when a test key is detected.

OAuth 2.0 Authorization

Instead of building your own identity capture UI, you redirect users to Toni. After they verify their identity, we redirect them back to your application with a secure authorization code.

1. Redirect the user

Send the user to our authorize endpoint.

GEThttps://api.vbtoni.com/oauth/authorize
const url = new URL("https://api.vbtoni.com/oauth/authorize");
url.searchParams.append("client_id", "part_12345");
url.searchParams.append("redirect_uri", "https://your-app.com/callback");
url.searchParams.append("scope", "identity professional_license");
url.searchParams.append("state", "xyz_123");

window.location.href = url.toString();

Webhooks

Toni uses webhooks to notify your application when an event happens in your account. Webhooks are particularly useful for asynchronous events like when a user's manual document review completes.

Example Webhook Payload
{
  "id": "evt_1Mgxyz...",
  "object": "event",
  "api_version": "2026-05-01",
  "created": 1681234567,
  "type": "verification.succeeded",
  "data": {
    "object": {
      "id": "usr_9abc...",
      "status": "verified",
      "claims": {
        "over_18": true,
        "profession": "Real Estate Agent"
      }
    }
  }
}

Signed Claims (JWT)

Once a user is verified, we issue cryptographic JWT claims. You can verify these independently using our public key.

toni™