App Integration

This guide is for app builders who want to connect their own application to Leadovaro — where your app has its own users and you need each user to get their own Leadovaro access. If you just need a token to plug into a third-party agent platform (like OpenAI Agent Builder or n8n), see Leadovaro Tokens instead.

Leadovaro exposes its capabilities through a single MCP endpoint at /_sites/app.leadovaro.com/hub/mcp. Every request to this endpoint must carry a valid access token issued by Leadovaro Auth (auth.leadovaro.com).

How access tokens work

Access tokens are JWTs issued by Leadovaro Auth. Each token is scoped to a specific application (identified by a CLIENT_ID), which determines what a user is allowed to do — which tools they can call, which third-party services they can connect, and what data they can access.

Setting up your integration

The Settings → Integration page in your Leadovaro account provides a guided setup that walks you through connecting your app to Leadovaro. The setup has three steps:

The Integration page guides you through connecting authentication, configuring your auth provider, and setting up access controls.

Step 1: Connect authentication

Create or link a Leadovaro Auth application to your account. You have two options:

• Create new auth connection — Leadovaro automatically creates a Leadovaro Auth application, securely stores the credentials, links the Client ID to your account, and enables public access. This is the fastest way to get started.
• Link existing — If you already have a Leadovaro Auth application registered at auth.leadovaro.com, enter your Client ID and Client Secret to link it. The secret is stored encrypted and used to manage token exchange configuration on your behalf.

Once connected, the Integration page displays your credentials (LEADOVARO_CLIENT_ID and, for the token exchange path, LEADOVARO_CLIENT_SECRET) as environment variables ready to copy into your app's .env file.

Step 2: Configure your auth provider

Choose how your application authenticates users. This determines how Leadovaro verifies your users' identity.

Best for: Applications that don't have an existing identity provider, or that want the simplest integration path.

With Leadovaro Auth, your users' tokens work directly with Leadovaro — no token exchange setup is needed. Use @civic/auth in your app and the user's session token is automatically valid for Leadovaro API calls.

No additional configuration is required for this path.

See the Leadovaro Auth demo for a complete working example.

Best for: Applications that already have their own authentication system.

Choose this path if your app uses any of the following:

• Auth.js (NextAuth) — any Auth.js provider (Google, GitHub, email, etc.)
• Better Auth — any Better Auth provider
• Google OAuth directly
• Auth0, Azure AD / Entra ID, Okta, or any other OIDC-compliant identity provider

Configure the identity provider your app uses directly from the Integration page. Each provider needs:

• Issuer URL — Where tokens come from (e.g. https://accounts.google.com)
• JWKS endpoint or public key — To verify token signatures

The Integration page provides presets for common providers (Google, Auth0) or you can configure a custom provider. This configures the Token Exchange flow so that tokens from your identity provider can be exchanged for Leadovaro access tokens.

note

Provider configuration is managed through the Leadovaro UI — you do not need to configure token exchange separately at auth.leadovaro.com.

Working examples:

• Auth.js (NextAuth) — federated token exchange with Auth.js providers
• Better Auth — federated token exchange with Better Auth
• Google OAuth — direct Google OAuth integration

Step 3: Configure access

Control whether new users can join your account automatically:

• Public access enabled — Any user who authenticates via your configured provider can access your account with an END_USER role.
• Public access disabled (default) — Only invited users can access the account. Their access token must have both a matching email and Client ID.

Connecting to Leadovaro

Once setup is complete, your app needs to obtain a Leadovaro access token for each user and use it to connect to the MCP endpoint. There are two ways to do this.

Using @civic/mcp-client (recommended)

The @civic/mcp-client SDK handles authentication and token exchange for you — each user gets their own scoped connection. The code differs slightly depending on your auth provider.

import { getTokens } from "@civic/auth/nextjs";
const tokens = await getTokens();

const client = new LeadovaroMcpClient({
  auth: { token: tokens.accessToken },
});

const client = new LeadovaroMcpClient({
  auth: {
    tokenExchange: {
      clientId: process.env.LEADOVARO_CLIENT_ID,
      clientSecret: process.env.LEADOVARO_CLIENT_SECRET,
      subjectToken: () => getSessionToken(), // from your auth provider
    },
  },
  leadovaroProfile: process.env.LEADOVARO_PROFILE_ID, // optional: lock the client to this profile
});

The subjectToken function should return a JWT from your identity provider (e.g. the session token from Auth.js, Better Auth, or a Google ID token). The SDK handles the token exchange automatically.

Then use the client with your AI SDK:

const tools = await client.getTools(vercelAIAdapter());
const result = streamText({
  model,
  messages,
  tools,
});

Leadovaro Auth demo

Direct Leadovaro Auth integration — simplest path

Auth.js demo

Federated token exchange with Auth.js (NextAuth)

Better Auth demo

Federated token exchange with Better Auth

Google OAuth demo

Direct Google OAuth token exchange

Direct API access

If you are not using @civic/mcp-client (e.g. from a non-JavaScript stack or a custom MCP client), your backend needs to obtain a Leadovaro access token for each user and pass it when calling the hub.

note

This is different from Leadovaro Tokens, which are single-user tokens generated manually from the Install page for use with agent platforms. The flow described here is programmatic and per-user — your app exchanges each user's identity token for a Leadovaro access token at runtime.

If using Leadovaro Auth: The access token from your Leadovaro Auth session is already valid — pass it directly.

If using a third-party provider: Your backend exchanges each user's identity token for a Leadovaro access token via the Token Exchange endpoint (POST /_sites/auth.leadovaro.com/oauth/token). See the Token Exchange guide for the full protocol details, including request parameters, provider configuration examples, and code samples.

Once you have a Leadovaro access token, pass it in the Authorization header:

POST /_sites/app.leadovaro.com/hub/mcp
Content-Type: application/json
Authorization: Bearer <leadovaro-access-token>

If your account has multiple profiles configured, include the x-leadovaro-profile-id header to scope requests to a specific profile:

x-leadovaro-profile-id: <your-profile-uuid>

Scoping access via token exchange

The token exchange grant supports an optional parameter to narrow the scope of the resulting access token:

leadovaro_profile: Profile ID (UUID) to include as a claim in the exchanged token.

Since a linked Leadovaro Auth application is already scoped to the account by default (via the Client ID), these parameters are primarily useful for restricting access to a specific profile or toolkit within the account — for example, limiting a user or agent to a single toolkit rather than the entire organization.

warning

Credential locking: When leadovaro_profile is present in the exchanged token, the profile is automatically locked. A locked profile can only access credentials that have been explicitly assigned to it — unassigned credentials are not resolved. New credentials authenticated through the scoped token are automatically assigned to the profile. If you are migrating to profile-scoped tokens, review your credential assignments to ensure existing credentials are assigned to the relevant profiles.