Overview

When an AI agent requests access to a user's resources via OAuth or another authentication method, the user sees a consent page before authorization is granted. Checkpoint provides a customizable consent flow that clearly communicates what the agent is requesting and gives the user full control over what to approve.

The consent UI is built with @kya-os/consent — a library of Web Components powered by Lit. Because it uses the Web Components standard, the library renders natively in any framework or no framework at all — React, Next.js, Vue, Angular, Svelte, or vanilla JavaScript.

Built on Web Components — renders natively in any framework

React

Next.js

Vue

Angular

Svelte

Vanilla JS

Live Preview

Switch between authentication modes to see how each consent screen appears to users:

Permission Request

Allow Shopping Assistant to access your account

This agent is requesting the following permissions:

Read your profile

View your files

Create and edit files

I agree to the I agree to the Terms of Service

This permission will expire in 7 days

These are live previews of the consent screens users see when authorizing an agent.

1. Agent initiates authorization request
2. User is redirected to the consent page
3. Consent page displays:
   - Agent identity (DID and display name)
   - Requested scopes in human-readable form
   - Your application branding
   - Authentication method (OAuth button, login form, or simple approve)
4. User authenticates (if required) and approves or denies
5. If approved → delegation is created, agent receives authorization
6. If denied → agent receives an error, no delegation is created

The consent page is hosted by Checkpoint and shows:

Your application name and logo (configured in dashboard)
Agent identity — The requesting agent's DID and display name
Requested permissions — Human-readable descriptions of each scope
Authentication UI — Varies by auth method (OAuth button, credentials form, or approve/deny)

Users can review exactly what they're granting before making a decision.

Via the Dashboard

Navigate to Project → Control Access → Consent
Configure:
- Application display name
- Application logo URL
- Custom description text
- Scope descriptions (human-readable names for each scope)
- Theme colors
Save and preview

Via the API

curl -X PUT https://kya.vouched.id/api/v1/bouncer/projects/{projectId}/consent-config \
  -H "X-API-Key: $CHECKPOINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "application_name": "My E-Commerce Store",
    "application_logo": "https://example.com/logo.png",
    "description": "Allow this AI agent to interact with your account",
    "scope_descriptions": {
      "cart:read": "View your shopping cart",
      "cart:write": "Add and remove items from your cart",
      "payment:process": "Complete purchases on your behalf",
      "profile:read": "View your profile information"
    },
    "theme": {
      "primary_color": "#1e2d57",
      "background_color": "#ffffff"
    }
  }'

Public Configuration Endpoint

The consent page fetches configuration from a public endpoint (no API key required):

curl -X GET https://kya.vouched.id/api/public/consent-config/{projectId}

Scope Descriptions

Map technical scope identifiers to user-friendly descriptions. This helps users understand what they're approving:

Scope	Description Shown to User
`files:read`	"View your files and documents"
`files:write`	"Create, edit, and upload files"
`cart:write`	"Add and remove items from your cart"
`payment:process`	"Complete purchases on your behalf"

Scopes without configured descriptions will display the raw scope identifier (e.g., files:write) to the user. Always provide human-readable descriptions for a better user experience.

Checkpoint manages consent state automatically:

Pending — User has been shown the consent page but hasn't responded
Approved — User approved, delegation created
Denied — User denied, no delegation created
Expired — Consent page timed out without a response

If the same agent requests the same scopes again, Checkpoint can optionally skip the consent page and reuse the existing delegation (if still active). Configure this behavior in the dashboard under Control Access → Consent.

Redirect Handling

After the user approves or denies consent:

Approved: Redirects to the agent's redirect_uri with an authorization code
Denied: Redirects to the agent's redirect_uri with an error=access_denied parameter

// Approved
https://agent.example.com/callback?code=auth_xyz&state=random_state

// Denied
https://agent.example.com/callback?error=access_denied&state=random_state

The consent UI is built with @kya-os/consent, a Web Component library powered by Lit. React wrappers are available via @kya-os/consent/react, and the raw custom elements (<mcp-consent>, <consent-shell>, etc.) work in any framework — Vue, Angular, Svelte, or plain HTML. You can use these components to embed consent experiences in your own applications or to preview the flow during development.

Available Components

Component	Purpose
`McpConsentReact`	Full consent flow (composite — includes all below)
`ConsentShellReact`	Container with branding (logo, colors, title)
`ConsentPermissionsReact`	Scope/permission list with optional checkboxes
`ConsentButtonReact`	Styled action button (Allow / Deny)
`ConsentCheckboxReact`	Checkbox with label (terms acceptance)
`ConsentInputReact`	Text input (username, email, password fields)
`ConsentTermsReact`	Terms & privacy policy checkbox with links
`ConsentOAuthButtonReact`	OAuth provider sign-in button

The McpConsentReact component renders the complete consent flow for any authentication method:

import { McpConsentReact } from '@kya-os/consent/react';

<McpConsentReact
  config={{
    branding: {
      primaryColor: '#2563eb',
      logo: { url: 'https://example.com/logo.png', alt: 'My App' },
    },
    ui: {
      title: 'Grant Access',
      description: 'Allow this agent to access your account',
    },
    terms: {
      termsText: 'Terms of Service',
      termsUrl: 'https://example.com/terms',
      privacyText: 'Privacy Policy',
      privacyUrl: 'https://example.com/privacy',
    },
  }}
  tool="checkout"
  scopes={['cart:read', 'cart:write', 'payment:process']}
  agentDid="did:key:z6Mk..."
  agentName="Shopping Assistant"
  onApprove={(e) => console.log('Approved:', e.detail)}
  onDeny={() => console.log('Denied')}
/>;

Compose individual components for a custom layout:

import {
  ConsentShellReact,
  ConsentPermissionsReact,
  ConsentTermsReact,
  ConsentButtonReact,
} from '@kya-os/consent/react';

<ConsentShellReact pageTitle="Permission Request" companyName="Acme Corp" primaryColor="#1e2d57">
  <div slot="content">
    <ConsentPermissionsReact
      scopes={[
        { id: 'files:read', label: 'Read your files', required: true },
        { id: 'files:write', label: 'Create and edit files' },
      ]}
      interactive
      selectAll
      iconStyle="shield"
    />
    <ConsentTermsReact
      text="Terms of Service"
      url="https://example.com/terms"
      privacyText="Privacy Policy"
      privacyUrl="https://example.com/privacy"
      required
    />
  </div>
  <div slot="footer">
    <ConsentButtonReact variant="secondary">Cancel</ConsentButtonReact>
    <ConsentButtonReact variant="primary">Allow Access</ConsentButtonReact>
  </div>
</ConsentShellReact>;

CSS Theming

The consent components respect CSS custom properties for consistent branding:

:root {
  --consent-primary: #2563eb; /* Primary brand color */
  --consent-secondary: #dbeafe; /* Secondary/accent color */
}

These are automatically set when you configure primaryColor and secondaryColor on ConsentShellReact or in the config.branding object.

During development, you can preview the consent page from the dashboard:

Navigate to Project → Control Access → Consent
Click Preview to see the consent page with your current configuration
Test with different scope combinations
Switch between authentication methods to preview each mode

The consent page preview uses sample data. In production, the actual agent DID and requested scopes are displayed.

Testing with Components

Install @kya-os/consent to render consent flows locally during development:

npm install @kya-os/consent

Import the React wrappers and render with test data:

import { McpConsentReact } from '@kya-os/consent/react';

// Use previewStep to render specific stages
<McpConsentReact
  previewStep="consent"
  config={yourConfig}
  scopes={['files:read', 'files:write']}
  agentName="Test Agent"
/>;

Next Steps

Authentication Methods — Choose the auth method for your consent flow
OAuth Integration — The full OAuth flow that triggers consent
Tool Protection — Define which scopes map to which tools
Managing Delegations — Delegations created after consent

Consent Flows