# Verified by Toni: live website integration

Updated September 17, 2026. Current guide: https://www.vbtoni.com/developers/docs

## Setup

Complete company onboarding and representative identity verification. In API Credentials, connect your website by publishing the supplied public meta tag in its homepage HTML head or the exact token at /.well-known/toni-verification.txt. Select Verify connection. No DNS or registrar login is required.

Only successful proof claims a website. A verified claim cannot belong to two workspaces; contact its owner or Toni support if already connected. Pending entries do not reserve it. Multiple apps in the same workspace can use a claim.

Select the verified website for new live credentials. Register the exact HTTPS callback URL on that host or its www alias; other subdomains need separate proof. Existing apps retain their keys and existing callback hosts. A new host needs a separate app.

Under Production, select Create credentials. Save the client secret in your server's secret manager when it is shown, then continue to Redirect URLs. Existing credentials have an explicit Add redirect URL or Edit redirect URLs button. If the one-time secret was missed, select Replace client secret and confirm: the old secret stops working immediately, while the client ID and callback settings remain unchanged. Update your server environment before retrying sign-in. Never paste the secret into an AI prompt.

Approved * is operational while company review is pending. It is not completed EIN or company verification. Website proof does not attest native app ownership.

The button and callback must be implemented in your application. Creating a key does not install Toni on your site.

## Approved button

Choose the tenant flow first under Toni button design in API Credentials. Use Login only when Toni is only the account bridge at entry and identity verification happens later in your app. Use Sign in or register when your entry point should offer both returning-user sign-in and new Toni account creation. Copy the matching embed and AI instructions for that exact flow. The combined option uses two real links and hosted v2 styling; a hosted SVG by itself cannot provide two clickable actions. Login-only variants are available in white, blue, black, gray, and red. Old blue, charcoal, white and soft artwork URLs and v1 embeds continue working for existing integrations. Do not use the legacy widget.js. Creating credentials does not install the control on your site.

## Authorization

The approved designs are Framed Pair (B) and Soft Duo (C). Both offer two separately framed full-row links: Sign in with Toni and Register with Toni. Borders are 1px; Soft Duo has white text on the blue registration row. In API Credentials choose the style and copy its complete embed and matching prompt. The two-row control uses https://www.vbtoni.com/api/brand/button-styles/v2 and the hosted white mascot. Permit https://www.vbtoni.com in style-src and img-src CSP. Do not inline or locally copy these assets. Compatible v2 styling updates refresh centrally after the five-minute asset cache window. No credentials or callback changes are needed. Old v1 embeds and the old artwork URLs remain supported; adopting the new two-row markup requires one embed replacement. Keep both partner-owned links, keyboard focus styling and visible labels. Never wrap the group in another link/button or flatten it into an image. With React, use className and put the stylesheet link in the page head once. Plain links remain usable if styling is unavailable. New markup or authentication changes can still require a deliberate integration update.

### Sign in and register

Choose Login only, Register, or Sign in or register in the button designer. You can place separate sign-in and register buttons using the same client ID and callback. The copied Register link uses `/api/auth/toni/start?intent=register`; your server must forward that intent as `screen_hint=signup` on the Toni authorization request. This opens email registration directly, without Toni's business plan picker. Only sign-in links omit the hint. Switching between sign-in and registration preserves the partner authorization request. Already signed-in users reuse their Toni identity.

Login only is authentication, not verification. After a valid callback, you may create an authenticated-but-unverified local session for onboarding. Do not unlock protected features that require identity or age until Toni returns server-validated claims that satisfy your requirements.

The hosted artwork's `action=register` or `action=signin` query changes only its label, not navigation. Update both the link and your server-side start route using the matching AI prompt. Never link directly to `/signin` and drop the OAuth context. Generate fresh state, nonce, and PKCE for every attempt. After validating the callback, identify users by issuer and subject, not email matching; new accounts on your own site must still complete your registration and terms requirements.

GET https://www.vbtoni.com/oauth/authorize with:
- client_id: your pk_live_ client ID
- redirect_uri: the exact registered callback
- response_type: code
- scope: openid id_verification (add email/profile only when needed)
- state: fresh cryptographically random value for this attempt
- nonce: fresh random value
- code_challenge: base64url SHA-256 of a fresh PKCE verifier
- code_challenge_method: S256

Store state, nonce, verifier, callback, and intended local account in your server-side session using a secure HttpOnly cookie. Do not treat browser storage as a universal fix for session or state errors.

## Callback and exchange

Handle error responses. Validate and consume state against that pending session before exchange. Reject mismatched or missing state.

POST https://www.vbtoni.com/api/oauth/token from your server with JSON:
```json
{
  "grant_type": "authorization_code",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_SERVER_ONLY_SECRET",
  "code": "CALLBACK_CODE",
  "redirect_uri": "EXACT_CALLBACK",
  "code_verifier": "SAVED_PKCE_VERIFIER"
}
```

Never put the client secret in frontend code or log secrets, codes, or tokens. Reject non-successful responses.

## Signed result

Read trusted configuration from https://www.vbtoni.com/.well-known/openid-configuration.
Validate the ID token with Toni's published JWKS, pinned issuer, your exact client ID as audience, RS256 signature, expiration, saved nonce, and type=id_token. Require verification_status=VERIFIED and evaluate required check results before granting access.

The sub claim is partner-app-scoped. Email and name are optional scope-dependent fields. Raw ID photos and biometric images are not shared. Existing results may require additional or recent checks; they are not permanent universal clearance.

Use the authorization callback and token exchange. There is no published partner webhook subscription API or Toni Node SDK webhook helper.

## Billing and acceptance

Business setup currently includes a $5 verification-credit purchase. Paid verification sessions start at $0.50, with optional checks priced a la carte. Payments are one-time, not subscriptions. The workspace funds checks it requests for its users. Eligible reuse has no new verification charge. Executed declined checks can still be charged.

Test denied consent, invalid state, reused or expired codes, callback mismatch, insufficient coverage, and revoked access. Production acceptance additionally requires a real payment, verification, and itemized billing reconciliation on the registered live site.