Quick Start
Get Checkpoint running in 5 minutes
Prerequisites
- A Checkpoint project, with its Project ID and API key to hand — see Credentials for where to find both.
- A running app on one of the stacks below (Next.js, Express, ASP.NET Core, or any site you can add a script tag to).
- Not sure which one to pick? Choose your integration compares them.
5-Minute Setup
Choose your preferred integration method and follow the steps below.
Install the package
npm install @kya-os/checkpoint-nextjsCreate middleware
Create middleware.ts in your project root:
Next.js 16: middleware.ts → proxy.ts
proxy.ts and export a proxy function (a default export also works); middleware.ts exporting middleware still works but is deprecated. The Checkpoint setup below is identical either way — only the file name and export name change. One caveat: proxy.ts runs on the Node.js runtime only, so if you want Checkpoint on the Edge runtime (lowest latency), keep the file as middleware.ts. On Next.js 15 and earlier, use middleware.ts.import { withCheckpointApi } from '@kya-os/checkpoint-nextjs/api-middleware';
export default withCheckpointApi({
apiKey: process.env.CHECKPOINT_API_KEY,
});
export const config = {
matcher: ['/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)'],
};Add environment variables
# .env.local
CHECKPOINT_API_KEY=your_api_key_hereSee Credentials for how to find your API Key and Project ID in the dashboard.
Verify Installation
After installation, verify Checkpoint is working:
Check the Dashboard
- Open the Checkpoint Dashboard
- Navigate to your project
- Open the Activity feed
- You should see detections appearing in near real time
Check Network Requests
- Open your browser's Developer Tools
- Go to the Network tab
- Look for requests to
kya.vouched.id - Successful requests return a
200status
Enable debug: true in your configuration (Beacon) or set data-debug="true" (Pixel) to see
detailed console output during development.
Environment Variables
We recommend using environment variables for configuration:
# .env or .env.local
CHECKPOINT_API_KEY=your_api_key_here # Server-side only — never expose to the browser
CHECKPOINT_PROJECT_ID=your_project_id_here # Not secret; used server-side and client-sideKeep your API Key secret. Never expose it in client-side code. The Project ID is not a
secret — server integrations read it (the Express example above passes it as projectId), and it
is also safe to expose to the browser for the Pixel and Beacon. For client-side use in Next.js,
prefix it so the bundler inlines it: NEXT_PUBLIC_CHECKPOINT_PROJECT_ID.
The SDKs read a few more environment variables directly — CHECKPOINT_API_URL,
CHECKPOINT_USE_EDGE, CHECKPOINT_DEBUG, and CHECKPOINT_SECRET. See
Credentials for the full table.
Next Steps
Now that Checkpoint is running:
- Dashboard Analytics — View detection data and trends
- Detection Methods — Understand detection approaches
- Enforcement — Set up active enforcement policies
- Govern (KYA-OS) — Control AI agent access with identity
- Choose Your Integration — Compare all integration options
Troubleshooting
Not detecting agents?
- Verify your Project ID is correct
- Check network requests in browser DevTools for errors
- Ensure middleware is in the project root (Next.js)
- Enable debug mode for detailed logs
Too many false positives?
- Review confidence scores in Analytics
- Adjust your policy rules
- Deploy your policy in observe mode before flipping to enforce
Performance issues?
- Enable WebWorker mode (Beacon — default)
- Use the Gateway for edge enforcement
- Review the Middleware docs for caching options