AgentAdmit App Owner Onboarding Guide

Everything an app owner needs to go from signup to live AI agent access in their app. Created: March 19, 2026

What You're Getting

AgentAdmit lets your users connect their personal AI agents to your app with scoped, secure, user-controlled access. You integrate once. Your users generate tokens, choose what their agent can do, and their agent connects automatically.

You don't build the auth flow. You don't build the token exchange. You don't build the agent access page. We give you all of that. You define what's accessible in your app (your scopes), write a few templates for your users, and drop in our components.

This works for any app with an API. Fitness apps, CRM platforms, e-commerce stores, project management tools, analytics dashboards, content platforms. If your app has API endpoints that do something useful, your users' AI agents can access them through AgentAdmit. The examples in this guide are generic, but the concepts apply to any app with an API.

How the flow works:

Your User → opens AgentAdmit page in YOUR app
         → selects permissions (scopes) for their agent
         → generates a connection token
         → personalizes a template ("Act as my fitness coach...")
         → sends the template + token to their AI agent in one message
         → the agent reads the token, discovers your API automatically,
           connects, and starts working based on the template

AgentAdmit sits between your app and the agent. It validates every request, enforces the scopes the user selected, and logs every action. Your app's actual data flows directly between the agent and your backend. AgentAdmit never sees your users' data. It only sees which scopes were granted, which endpoints were called, and when.

What's included:

What's NOT included until you pay:

Live API keys. Test keys work identically to live keys but only in your development environment. They still use AgentAdmit's hosted service and still require mandatory introspection on every protected request. Terms of Service and Privacy Policy acceptance should happen before test key issuance, not only before going live. When you're ready to go live, activate your subscription (starting at Starter $50/mo) and your live keys unlock automatically. No code changes needed between test and live.

Handing Off to a Developer or AI Coding Agent

You don't have to do the integration yourself. You can hand it to a developer or an AI coding agent. Here's exactly what to give them:

What to hand over:

1. This guide (the URL at agentadmit.com/docs/getting-started, or the document itself)
2. Your App ID and test API keys (from Step 1 below)
3. Access to your codebase (repo access, or the coding agent is already in your project)
4. A brief description of your app's main user workflows (so they can write templates). For example: "Users track workouts and meals. Trainers create plans for clients. Admins view analytics."

That's it. This guide contains everything they need: SDK install, code examples, data structures, testing steps. They will come back to you for decisions only they can't make:

• Which endpoints should agents access (your business decision)
• What templates should say (your domain knowledge)
• Approval before going live (your call)

This guide is designed to be self-contained. A developer or AI coding agent with this document + your credentials + your codebase can complete the entire integration without needing any other documentation. For standard frameworks (Python, Node, Java, PHP, Ruby, Go, React), everything is here. For unsupported frameworks, the API reference at agentadmit.com/docs has the endpoint specs.

Let Your AI Coding Agent Do the Integration

If you use a coding agent (Claude Code, OpenAI Codex, an OpenClaw coding agent, Cursor, Windsurf, or any AI-powered IDE), you can hand it this guide along with your codebase and let it do the integration for you.

What the coding agent can do automatically:

• Install the correct backend SDK for your framework
• Scan your existing API endpoints and suggest scopes
• Add AgentAdmit middleware to your routes
• Set up the React component in your frontend
• Configure your environment variables

What the coding agent will ask YOU about:

• Which endpoints should agents be able to access (your scopes are your decision)
• What your templates should say (personalized requests are your domain knowledge)
• Your App ID and API keys (it needs your credentials from the dashboard)

How to do it: Open your coding agent in your project directory, give it this onboarding guide (the full text or the URL at agentadmit.com/docs/getting-started), and tell it: "Integrate AgentAdmit into this project. Follow the guide. Ask me for any decisions you can't make on your own."

The agent will work through the steps below, ask you the right questions when it needs your input, and handle the rest. If you prefer to do it yourself, follow the steps manually.

Step 1: Sign Up and Get Your Keys

Go to agentadmit.com and create your account.

You'll immediately get two credentials:

Where to store them: Create or update your .env file:

AGENTADMIT_APP_ID=app_7kBx9mQ2
AGENTADMIT_API_KEY=aa_test_Rz4pN8...

Your App ID is safe to reference in frontend code. Your API Key must stay server-side only. AgentAdmit handles RSA token signing for you — there is no separate "secret" key for you to manage.

Step 2: Install Your Backend SDK

Pick the one that matches your stack and follow the quickstart:

Python (Flask)

pip install agentadmit

# app.py
from flask import Flask
from agentadmit.integrations.flask_integration import AgentAdmitFlask

app = Flask(__name__)
aa = AgentAdmitFlask(app, config_path="agentadmit.yaml")

# Protect a route with a scope
@app.route('/api/workouts')
@aa.require_scope_if_agent('read:workouts')
def get_workouts():
    return get_user_workouts()

Python (Django)

pip install agentadmit

# settings.py
MIDDLEWARE = [
    # ...
    'agentadmit.integrations.django_integration.AgentAdmitMiddleware',
]

AGENTADMIT_CONFIG = {
    'config_path': 'agentadmit.yaml',
}

# urls.py
from agentadmit.integrations.django_integration import agentadmit_urls
urlpatterns += agentadmit_urls

# views.py
from agentadmit.integrations.django_integration import require_scope_if_agent

@require_scope_if_agent('read:workouts')
def get_workouts(request):
    return get_user_workouts(request)

Node.js (Express)

npm install @agentadmit/sdk

// app.js
const { agentAdmit } = require('@agentadmit/sdk');

const aa = agentAdmit({
  appId: process.env.AGENTADMIT_APP_ID,
  apiKey: process.env.AGENTADMIT_API_KEY,
  verifyUrl: 'https://api.agentadmit.com/v1/verify',
});

// Mount AgentAdmit routes (token exchange, connections)
app.use('/agentadmit', aa.routes());

// Protect a route with a scope
app.get('/api/workouts', aa.requireScope('read:workouts'), (req, res) => {
  res.json(getWorkouts(req.user.id));
});

Java (Spring Boot)

# application.yml
agentadmit:
  app-id: app_7kBx9mQ2
  api-key: aa_test_...
  verify-url: https://api.agentadmit.com/v1/verify

@GetMapping("/api/workouts")
@AgentAdmitScope("read:workouts")
public List<Workout> getWorkouts() {
    return workoutService.getAll();
}

PHP (Laravel)

composer require agentadmit/laravel
php artisan vendor:publish --tag=agentadmit

// config/agentadmit.php is auto-published. Add keys to .env:
// AGENTADMIT_APP_ID=app_7kBx9mQ2
// AGENTADMIT_API_KEY=aa_test_...

// routes/api.php
Route::middleware('agentadmit:read:workouts')->get('/workouts', [WorkoutController::class, 'index']);

Ruby (Rails)

gem 'agentadmit'
bundle install
rails generate agentadmit:install

# config/initializers/agentadmit.rb is auto-generated. Add keys to credentials or .env.

# app/controllers/workouts_controller.rb
class WorkoutsController < ApplicationController
  include AgentAdmit::ScopeEnforcement

  before_action -> { require_scope_if_agent!('read:workouts') }

  def index
    render json: current_user.workouts
  end
end

Go (net/http, Gin, Echo)

go get github.com/agentadmit/agentadmit-go

import "github.com/agentadmit/agentadmit-go"

client, _ := agentadmit.New(agentadmit.Config{
    APIKey:    os.Getenv("AGENTADMIT_API_KEY"),
    VerifyURL: "https://api.agentadmit.com/v1/verify",
})

// net/http
mux.Handle("/api/workouts", agentadmit.RequireScopeIfAgent(client, "read:workouts", workoutsHandler))

// Gin
r.GET("/api/workouts", gin.RequireScopeIfAgent(client, "read:workouts"), workoutsHandler)

// Echo
e.GET("/api/workouts", workoutsHandler, echo.RequireScopeIfAgent(client, "read:workouts"))

What each SDK does automatically after setup:

• Creates the token exchange endpoint (POST /agentadmit/token)
• Creates connection management endpoints (list, revoke)
• Creates the discovery document at /.well-known/agentadmit
• Validates agent tokens via mandatory introspection on every protected request
• Blocks requests where the agent lacks the required scope
• Returns clear error messages when permissions are missing

About mandatory introspection: Every agent request is validated through AgentAdmit's hosted service in real time. This is not optional and cannot be bypassed. There is no self-hosted validation mode and no local JWT verification. This ensures every agent action is authenticated, scoped, logged, and revocable from a single point. It also means you get full audit logs of all agent activity in your dashboard without building anything yourself. The introspection adds minimal latency (typically under 200ms) and only applies to agent requests, never to your regular user traffic.

Step 3: Define Your Scopes

Scopes define what an AI agent can do in your app. You decide what's accessible.

Where to define them: In your SDK configuration file. The exact format depends on your framework, but the structure is the same:

// Example: Node.js/Express scope definitions
const scopeResources = [
  {
    group: 'Fitness Data',
    scopes: [
      { id: 'read:workouts', label: 'View workouts', description: 'Access workout history and routines' },
      { id: 'create:workouts', label: 'Create workouts', description: 'Add new workout entries' },
      { id: 'read:meals', label: 'View meals', description: 'Access meal logs and nutrition data' },
      { id: 'create:meals', label: 'Create meals', description: 'Add new meal entries' },
    ]
  },
  {
    group: 'Analytics',
    scopes: [
      { id: 'read:analytics', label: 'View analytics', description: 'Access personal stats and progress' },
    ]
  },
  {
    group: 'Settings',
    scopes: [
      { id: 'manage:settings', label: 'Manage settings', description: 'Update profile and preferences' },
    ]
  }
];

How to decide what scopes you need:

Look at every API endpoint in your app. For each one, ask:

1. Should a user's AI agent be able to call this? (If no, skip it.)
2. Is this a read or a write? (Separate them. Users often want read-only first.)
3. Is this sensitive? (Billing, account deletion, password changes: probably skip these.)
4. Does this endpoint trigger in-app AI? If your app has built-in AI features (AI analysis, AI-generated plans, AI photo recognition), do NOT expose those as agent scopes. The user's AI agent IS an AI. It can read the raw data and do the analysis itself. Exposing in-app AI endpoints to an agent means double cost: the user pays for their agent's model AND your app pays for the in-app AI call. Instead, give the agent read access to the same data the in-app AI uses. The agent does its own analysis. Cheaper for you, cheaper for the user, and the agent is likely using a more capable model anyway.

Naming convention: action:resource

• read:workouts, create:meals, manage:settings
• Keep them human-readable. Your users see these names when selecting permissions.

Example for a non-fitness app (CRM):

read:contacts         - View contact list and details
create:contacts       - Add new contacts
read:deals            - View deal pipeline
manage:deals          - Create, update, close deals
read:analytics        - View sales analytics
send:emails           - Send emails on behalf of the user

How many scopes is typical? Most apps start with 10-30 scopes. Large apps may have 50-100+ scopes covering every endpoint. Start with the basics and add more as needed.

How middleware enforcement works: When you add requireScope('read:workouts') to a route, the SDK middleware:

1. Checks if the request has an AgentAdmit access token (in the Authorization header)
2. If yes, sends the token to AgentAdmit for introspection (validation + scope check)
3. If the token is valid AND has the required scope, the request proceeds
4. If the token is missing the scope, it returns a 403 with a message telling the agent which permission is needed
5. If it's a regular user request (no AgentAdmit token), the middleware passes through normally. Your existing user auth is unaffected.

Step 4: Add the React Component (Frontend)

npm install @agentadmit/react

Basic Setup

import { AgentAdmitPanel } from '@agentadmit/react';
import '@agentadmit/react/styles.css'; // Built-in styles (optional, override with your own CSS)

function AgentAccessPage() {
  const { user, sessionToken } = useYourAuthHook(); // Your existing user auth

  return (
    <AgentAdmitPanel
      apiBase="/agentadmit"
      authToken={sessionToken}
      userRole={user.role}
      appName="Your App Name"
      scopeResources={scopeResources}
      templates={templates}
      editableFields={editableFields}
      exampleCategories={examplePrompts}
      durationOptions={[
        { label: '30 minutes', seconds: 1800 },
        { label: '1 hour', seconds: 3600 },
        { label: '24 hours', seconds: 86400 },
        { label: '7 days', seconds: 604800 },
        { label: '30 days', seconds: 2592000 },
        { label: 'Until I revoke', seconds: 315360000 },
      ]}
    />
  );
}

Where to put it in your app: Create a dedicated page or tab for AgentAdmit. Common placements:

• Sidebar navigation item leading to its own page (recommended)
• Tab within your Settings or Account page
• Dedicated route like /settings/agent-access or /ai-agent

The component is a full page. It handles its own layout, sections, and state. Just give it a page and it fills it.

About authToken: This is YOUR app's session token for the currently logged-in user. It's how AgentAdmit knows which user is generating the connection token. The SDK sends this to your backend, which verifies it through your existing auth system. AgentAdmit doesn't handle your user login. It just needs to know who the current user is.

About userRole: If your app has different user types (e.g., "user", "trainer", "admin"), pass the role here. Templates and scopes can be filtered by role so each user type sees only what's relevant to them.

About durationOptions: These are the choices your users see for how long their agent stays connected. You decide what options to offer. Most apps include short durations (30 min, 1 hour) for one-time tasks and longer ones (7 days, 30 days, until revoked) for ongoing automation.

Styling: The SDK includes built-in CSS that works in light and dark modes. Import @agentadmit/react/styles.css for the defaults. All classes are prefixed with aa- so they won't conflict with your existing styles. Override any class to match your app's design.

What this component gives your users out of the box:

• "How It Works" 3-step guide at the top
• Scope selection with presets and custom options
• Duration picker
• Token generation with security guidance
• "Next Step" bridge that guides users to the templates
• Scope-filtered prompt templates with editable fields
• "Things You Can Ask" quick prompts
• Saved templates (users can personalize and save for reuse)
• Connection management (view active connections, revoke any time)

Data Structures for Props

scopeResources (what agents can access):

const scopeResources = [
  {
    group: 'Fitness Data',        // Group label shown in UI
    scopes: [
      {
        id: 'read:workouts',      // Scope ID (matches your middleware)
        label: 'View workouts',   // Human-readable label
        description: 'Access workout history and routines', // Shown on hover/expand
      },
      // ...more scopes
    ]
  },
  // ...more groups
];

templates (personalized prompts for the agent):

const templates = [
  {
    id: 'fitness-coach',
    title: 'Full Fitness Coach',
    subtitle: 'Workouts + meals + tracking',
    requiredScopes: ['read:workouts', 'read:meals', 'create:workouts', 'create:meals'],
    role: 'user',                 // Only shown to users with this role (optional)
    isHero: true,                 // Featured/highlighted template (optional)
    editableFields: ['fitness_goal', 'workout_days'],  // Keys from editableFields
    template: `Act as my personal fitness coach on {{app_name}}.

My fitness goal is: {{fitness_goal}}
I want to work out {{workout_days}} days per week.

Review my recent workouts and meals, identify patterns,
then create a personalized workout plan for the next week.`,
  },
  // ...more templates
];

editableFields (the personalization inputs):

const editableFields = {
  fitness_goal: {
    label: 'Your fitness goal',
    placeholder: 'e.g., lose weight, build muscle, improve endurance',
    default: 'general fitness',
  },
  workout_days: {
    label: 'Workout days per week',
    placeholder: 'e.g., 3, 4, 5',
    default: '4',
  },
};

exampleCategories (quick one-line prompts):

const exampleCategories = [
  {
    id: 'workouts',
    title: 'Workout Questions',
    scopes: ['read:workouts'],    // Only shown if user selected these scopes
    examples: [
      'What workouts did I do this week?',
      'Am I hitting my weekly volume targets?',
      'Create a push/pull/legs split for me',
    ],
  },
  // ...more categories
];

Templates can work without editable fields. If you don't want personalization, just omit the editableFields prop and don't include {{field}} placeholders in your template text.

Templates are dynamic. When a user selects their scopes, the component automatically shows only the templates that match those scopes. If a user selects read:workouts and create:workouts but not read:meals, they only see workout-related templates. Templates requiring meal scopes are hidden. This happens automatically based on the requiredScopes field in each template definition. You define the templates once and the component handles the filtering.

You can skip templates entirely. The component still works for scope selection and token generation. But templates significantly improve the user experience because users know exactly what to say to their agent.

Step 5: Write Your Templates

Templates are how your users tell their AI agent what they want. They are NOT technical instructions for connecting.

Why not? Because the connection part is handled automatically by the self-describing token. When the agent exchanges the token, it receives everything it needs: endpoints, methods, data structures. The template is purely the user's personalized request.

What a template IS: "Act as my fitness coach, review my workouts, create a plan." What a template IS NOT: "Connect to the API at this URL, use this auth header, call these endpoints."

How to write good templates:

1. Start with a role: "Act as my personal fitness coach on [App Name]"
2. Include editable fields for personalization (wrapped in {{double_braces}})
3. Be specific about what the agent should DO
4. Match the template to the scopes it requires
5. Keep it conversational. The user is talking to their agent, not writing code.
6. One template per use case. A "Full Coach" template, a "Meal Planner Only" template, a "Quick Check-in" template.
7. Include platform best practices. The self-describing token tells the agent what endpoints exist and what parameters to send. But your templates can include guidance on HOW to use your platform effectively. For example, a video generation platform might include: "Use style X for cinematic quality. Set resolution to 1080p for social, 4K for website. For character consistency, include detailed physical descriptions." This platform-specific knowledge helps the agent produce better results. The user doesn't need to know these details, as they're baked into the template by you, the app owner.
8. Include your documentation URL. Some users want their agent to fully understand your platform before creating anything. Include your docs URL in a "Learn First" template: "Read the documentation at [URL] first, then tell me what options are available, then let's decide together." The agent reads your docs, understands your platform's capabilities, and helps the user make informed choices. One template makes your platform self-explanatory to any AI agent.

More template examples. These show what real templates look like for a fitness app. Your templates will be specific to YOUR app and YOUR users' workflows:

Workout Planner (requires read:workouts, create:workouts):

You are my workout assistant on this fitness app.
My goal: {{fitness_goal}}
Review my workout history so you understand where I am.
Then create routines for me: {{workout_days}} days per week,
{{workout_duration}} per session. Log my workouts when I tell you what I did.

Find a Trainer (requires read:trainers):

Help me find a personal trainer.
I'm looking for someone who specializes in: {{specialization}}
Budget: {{budget}} per session
Preferred format: {{session_type}}
Location: {{location}}
Search the available trainers, compare their profiles, and recommend
the best matches based on my priorities: {{trainer_priorities}}

Trainer Business Assistant (requires read:clients, read:analytics, for trainer role):

You are my business assistant for my personal training practice.
Review my client list, check for inactive clients, pull my latest analytics,
and give me a daily brief: who needs follow-up, what's my client retention
looking like, and any red flags I should address today.

Notice how each template targets a different user type (user, user searching for a trainer, trainer running their business) and requires different scopes. The component shows each user only the templates relevant to their role and selected scopes.

"Things You Can Ask" examples. These are the kind of quick one-line prompts your users can copy and send to their agent. Write yours based on what YOUR app does:

These are one-line prompts users can copy and send to their agent. They're organized by category and filtered by scope:

Workouts (shown when user selects workout scopes):

• "I need a push day with bench press, overhead press, and tricep work"
• "Create a leg day focused on squats and Romanian deadlifts"
• "Just finished my push day as planned. Log it."
• "Hit a bench press PR, 225 for 3 reps! Log it"

Nutrition (shown when user selects meal scopes):

• "Make me a high protein meal plan around 2000 calories for the week"
• "Had chicken breast with rice and broccoli for lunch. Log it."
• "Had a cheat meal, pizza, about 800 calories. Log it, no judgment"

Messaging (shown when user selects message scopes):

• "What did my trainer say?"
• "Tell my trainer the workout was brutal today"

These give users immediate ideas for what to say to their agent. Users can copy any of these and send them to their agent along with their token.

How many templates should you start with? 2-4 is a good starting point. One broad template that uses most scopes, and 2-3 focused ones for specific tasks. A large app might have 10+ templates covering different user roles.

Can users save templates? Yes. The React SDK includes a saved templates feature. Users can personalize a template, save it with a custom name, and reuse it for future connections. You don't need to build this. It's built in.

Which AI Agents Can Your Users Use?

Your users need an AI agent that can make HTTP API calls. That's the only requirement. The agent receives the token, makes an HTTP POST to exchange it, then uses the access token to call your API endpoints.

Compatible agents (verified):

What does NOT work:

• AI chatbots without tool use / HTTP call capability (basic chat-only interfaces)
• Claude Cowork (designed for office tasks like Gmail/Drive, not general API calls)

What happens if a user gives the token to an incompatible agent? The agent won't know how to exchange the token. It will either ignore it, treat it as plain text, or tell the user it can't make HTTP requests. The token expires after 15 minutes regardless. No security risk, just a failed attempt. The user would need to use a compatible agent.

Important: AgentAdmit is agent-agnostic. We don't require or endorse any specific AI platform. Any agent that can make HTTP requests can use AgentAdmit tokens. The list above reflects what's commonly available as of 2026, but new agents and platforms emerge regularly.

What to tell your users: Your AgentAdmit page (the React component) includes a "Which agents can use this token?" section that lists compatible agents. This is built into the component so you don't need to maintain this list yourself.

Step 6: Understanding Self-Describing Tokens

This is the part most app owners wonder about: "How does the AI agent know what to do with the token?"

You don't need to build this. It's built into the protocol.

When your user generates a token and gives it to their agent, here's what happens:

1. The user gives the agent the token AND their personalized template in one message. Something like: "Here's my token: ag_ct_aHR0c... and here's what I want you to do: [template text]"

2. The agent reads the token. The token format is self-describing: ag_ct_<base64url(exchange_url)>.<secret>. The exchange URL is encoded right in the token. The agent splits the token on the period, decodes the first part, and knows exactly where to exchange it. No instructions needed.

3. The agent calls the exchange URL. AgentAdmit validates the token and returns:

   • An access token (JWT for making API calls to your app)
   • A list of every endpoint the agent can access (based on scopes the user selected)
   • The HTTP method for each endpoint (GET, POST, PUT, DELETE)
   • The exact data structure each endpoint expects (request body schemas with field names, types, and required fields)

4. The agent reads the template to know what the user WANTS. Then it uses the exchange response to know HOW to do it. It makes API calls to your app with the access token.

5. Your app's SDK middleware validates every request through AgentAdmit's introspection endpoint. Valid token + correct scope = request proceeds. Missing scope = 403 with a message about which permission is needed.

The user's template says WHAT. The token exchange says HOW. Two layers, cleanly separated.

This means:

• You don't put API documentation in your templates
• You don't tell agents how to authenticate
• Different AI models don't need different instructions
• It works with any AI agent that can make HTTP calls (Claude Code, Codex, OpenClaw, Gemini CLI, and custom agents built with function calling)

What this means for you as the app owner:

• Your request body schemas are generated automatically from your endpoint definitions. Make sure your endpoints have clear parameter names and validation. If your endpoint expects { "name": "Leg Day", "exercises": [...] }, that exact structure is what the agent receives in the exchange response.
• You do NOT need to put API documentation, connection instructions, or endpoint URLs in your templates. The token handles all of that.
• Your templates should focus entirely on the USER'S intent: what they want their agent to do, in their own words, with personalization fields for their preferences.
• If you're wondering "but how will the agent know my API?" the answer is: the token exchange tells it everything. That's what self-describing means.

Step 7: Test End to End

Before going live, test the full flow. You can test with an AI agent OR with curl/Postman.

Testing with an AI Agent

1. Open your AgentAdmit page in your app (the React component you set up)
2. Select some scopes and generate a test token
3. Copy a template and the token
4. Open your AI agent (Claude Code, Codex, OpenClaw, or any agent with HTTP access) and paste both
5. Watch the agent exchange the token and start making API calls

Testing with a Coding Agent

You can also use Claude Code, Codex, or any coding agent to run the full test. Give it your test token and tell it: "Exchange this AgentAdmit token, then test every endpoint you have access to. Report what works and what doesn't." The coding agent will make the HTTP calls through AgentAdmit's hosted introspection just like any other agent would. Test keys authenticate with the hosted service identically to live keys.

This is not just a developer convenience. It is a real future use case: app owners can use AgentAdmit to give QA agents and coding agents scoped, temporary, auditable access to staging environments for end-to-end testing, regression checks, consent validation, and protected-route verification.

Testing with curl (no AI agent needed)

Step 1: Generate a connection token (through your app's UI, or via API if your auth supports it):

# Generate a connection token (requires your app's user auth)
curl -X POST http://localhost:YOUR_PORT/agentadmit/connections/generate-token \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_USER_SESSION_TOKEN" \
  -d '{"scopes": ["read:workouts", "create:workouts"], "duration_seconds": 3600}'

Step 2: Exchange it (this is what the agent does):

# Exchange the connection token
curl -X POST http://localhost:YOUR_PORT/agentadmit/token \
  -H "Content-Type: application/json" \
  -d '{"connection_token": "ag_ct_YOUR_TOKEN_HERE", "grant_type": "connection_token"}'

The response includes your access token and the full endpoint map. Then test an endpoint:

# Use the access token to call a protected endpoint
curl http://localhost:YOUR_PORT/api/workouts \
  -H "Authorization: Bearer ACCESS_TOKEN_FROM_ABOVE"

What to Verify

Where to View Logs

Your AgentAdmit dashboard (agentadmit.com) shows:

• Every token exchange
• Every introspection request (which agent called which endpoint)
• Active connections and their scopes
• Error rates and failed requests

Step 8: Go Live

Pre-Launch Checklist

Before activating live keys, confirm:

• All scopes are defined and mapped to the correct endpoints
• Middleware is applied to every endpoint that agents should access
• Endpoints that agents should NOT access have NO AgentAdmit middleware
• Templates are written and tested
• Token generation, exchange, and scope enforcement all tested
• Token expiration and revocation tested
• The React component renders correctly in your production build
• Your .env.production has placeholder keys ready to swap

Activate

1. Go to your AgentAdmit dashboard (agentadmit.com)
2. Navigate to Billing
3. Activate your subscription (starting at Starter: $50/mo)
4. Your live keys appear immediately

Deploy

Swap your test keys for live keys in your production environment:

# .env.production
AGENTADMIT_APP_ID=app_7kBx9mQ2           # Same App ID
AGENTADMIT_API_KEY=aa_live_Xp9mN4...     # Live key (replaces aa_test_...)

Deploy your app. That's it. No code changes. Same SDK, same components, same flow.

What Happens to Test Connections?

When you switch from test keys to live keys, all test connections stop working. Test and live environments are completely separate. Your users will generate new connections with live keys. This is expected and clean. No test data carries over to production.

Can I Change Scopes After Go-Live?

Yes. You can add new scopes at any time. Existing agent connections keep their original scopes. New connections can include the new scopes. If you remove a scope from your code, existing connections that had it will get 403 errors on those endpoints. The agent will tell the user the permission is no longer available.

If Something Goes Wrong

• Agents can't connect: Check that live keys are correctly set in your production environment. The most common issue is accidentally keeping test keys.
• Scopes not enforcing: Verify your middleware is applied in production. Some deployment pipelines skip middleware registration.
• Need to roll back: Swap live keys back to test keys in your environment config and redeploy. Your app continues working for regular users. Agent connections stop validating until you restore the live keys.

Quick Reference

Your app's AgentAdmit endpoints (created automatically by the backend SDK):

The discovery document at /.well-known/agentadmit is a public JSON file that describes your app to AgentAdmit. It includes your app name, API base URL, and the scopes you support. The SDK generates this automatically from your scope definitions. You don't need to create or maintain it.

Your responsibilities:

• Define your scopes (what agents can access)
• Write templates (what users tell their agent to do)
• Add SDK middleware to your protected routes
• Drop the React component into your frontend

Admin capabilities (you as the app owner):

• View all active agent connections across your app: which users, which agents, which scopes, when they connected
• Revoke any user's agent connection instantly if you detect abuse — from your AgentAdmit dashboard or via the revoke API
• Full audit trail of every agent action through mandatory introspection. Use it for usage-based billing, compliance, abuse detection, or analytics.
• Give your own AI agent admin access to monitor your app. Generate a token with admin scopes and set the duration. Want full automation? Schedule your agent to watch your app while you sleep: usage alerts, connection monitoring, automated abuse response.
• Embed the <AgentAdmitAdminPanel> React component in your own admin dashboard. Four tabs: Connections (all users, search/filter, revoke), Usage (calls vs tier), Alerts (thresholds + kill switch), Activity (full audit trail). Auto-refreshes. Or use the AgentAdmit dashboard at agentadmit.com.

AgentAdmit's responsibilities:

• Token generation and exchange
• Mandatory introspection (every agent request is validated)
• Scope enforcement
• Connection management
• Audit logging
• Self-describing token format (agents discover your API automatically)
• Request body schemas (agents know what data to send)
• Connection Token security: hashed at rest, never stored in plaintext (spec §5.3.1). The SDKs handle this automatically.

What your users do:

1. Open the AgentAdmit page in your app
2. Read the "How It Works" guide (built into the component)
3. Choose what their agent can do (select scopes)
4. Choose how long the connection lasts (duration)
5. Generate a token
6. Personalize a template
7. Send the template and token to their AI agent in one message
8. Their agent connects and gets to work

Best Practices & Recommendations

Before going live, review these recommendations:

• Do not expose internal AI endpoints to external agents. If your app has built-in AI features (analysis, generation, recommendations), do not create scopes that let agents call those endpoints. The user's AI agent can read the raw data and do its own analysis. Exposing in-app AI to agents means double cost with no benefit. See the scope design section above for details.
• Implement rate limiting on your own endpoints. AgentAdmit handles authorization. You handle volume. Set per-agent, per-user rate limits to protect your infrastructure from runaway agents.
• Isolate agent-accessible endpoints. Keep endpoints that agents can reach separate from internal admin endpoints. Agents should only access what you explicitly define as scopes.
• Use test keys in staging before switching to live keys. Validate your entire integration with test keys first. The behavior is identical — only the environment changes.
• Monitor your dashboard regularly. Check active connections, alert events, and usage patterns. Set up webhook delivery for alerts so your system can react automatically.

Rate Limiting: Protect Your App and Understand AgentAdmit's Limits

AgentAdmit's rate limits on your introspection calls

AgentAdmit enforces rate limits on token verification calls to the hosted service. These limits vary by your plan:

• Test keys: Lower rate limits appropriate for integration testing and staging validation
• Starter ($50/mo): Production rate limits (250K calls/mo included)
• Builder ($100/mo): Higher production rate limits (500K calls/mo included)
• Pro ($200/mo): High volume production (1M calls/mo included)
• Enterprise: Custom limits available — contact us

When your app's verification call hits a rate limit, AgentAdmit returns HTTP 429 with a Retry-After header. All AgentAdmit SDKs handle this automatically with exponential backoff and retry. You can configure retry behavior in your SDK settings.

Your dashboard shows your current usage vs your plan's limits so you can monitor in real time.

Protect your own endpoints from agent overuse

AgentAdmit authorizes which agents can access your app and what scopes they have. But authorization alone does not control how frequently an agent calls your endpoints.

You should implement rate limiting on your own API endpoints to control how often agents can make calls. Use the user_id and agent identity from the AgentAdmit verify response to set per-agent rate limits appropriate for your application.

For example:

• Allow 60 read requests per minute per agent
• Allow 10 write requests per minute per agent
• Return HTTP 429 with a Retry-After header when an agent exceeds your limits

This protects your infrastructure from runaway agents, buggy integrations, or excessive automated testing. AgentAdmit handles the authorization. Your rate limits handle the volume.

Security Alerts & Kill Switch

AgentAdmit monitors every agent connection for anomalous behavior through the mandatory introspection audit trail. Six alert types are built in:

Configure Thresholds

You configure alert thresholds from the Security Alerts tab in your AgentAdmit dashboard, or programmatically via the SDKs:

from agentadmit import configure_alerts

configure_alerts(
    app_id="app_abc123",
    alert_type="volume_spike",
    threshold_value=3,         # 3× rolling average
    threshold_window_minutes=30,
)

import { configureAlerts } from '@agentadmit/sdk';

await configureAlerts({
  appId: 'app_abc123',
  alertType: 'burst_pattern',
  thresholdRatePerMinute: 100,
});

Kill Switch

Enable the kill switch on any alert type to automatically revoke the connection when the threshold is breached. The agent's next API call will fail with connection_revoked. You can enable kill switches from the dashboard or via SDK.

Config Hierarchy: You Set the Baseline, Users Can Tighten

You set the baseline thresholds for all connections to your app. Your users can tighten these for their own connections (lower thresholds, shorter windows) but can never loosen them past your baseline. If you enable a kill switch, users cannot disable it.

Users configure their own alert thresholds through the React SDK components you embed in your app:

import { AlertsPanel } from '@agentadmit/react';

<AlertsPanel apiBase="/agentadmit" authToken={user.jwt} appId="app_abc123" />

Monitoring Alert Events

Query alert events from the AgentAdmit dashboard or programmatically:

from agentadmit import list_alerts

events = list_alerts(app_id="app_abc123", alert_type="volume_spike")
for event in events:
    print(f"{event['alert_type']}: {event['severity']} — {event['details']}")

Notifying Your Users Is Your Responsibility

AgentAdmit detects anomalies, fires alerts, and (with kill switch) auto-revokes connections. How you notify your own users about these events is up to you.

AgentAdmit provides the data. You deliver it through your own system — in-app notifications, email, push, SMS, or however your app communicates with users. Here's the pattern:

1. Poll alerts via SDK — Use list_alerts() from your backend to check for new events, then notify your users through your existing notification system.
2. Webhook delivery (coming soon) — Configure a webhook URL in your AgentAdmit dashboard. When an alert fires, AgentAdmit sends an HTTP POST to your server with the full alert payload. Your server handles the notification to the affected user.
3. React SDK for user self-service — Embed the <AlertsPanel> component so users can view their own alert history and tighten their thresholds directly.

This design is intentional. You know your users, your notification infrastructure, and your UX. AgentAdmit gives you the security data — you decide how to surface it.

Common Questions

On agentadmit.com/docs, these FAQs are searchable. If you can't find your answer here, contact support.

Q: Do I need to build an agent access page from scratch? No. The React SDK gives you a complete, ready-to-use page. Just provide your scopes and templates.

Q: What if my backend framework isn't listed (Go, Rust, .NET, etc.)? The backend SDK covers Python (FastAPI/Flask/Django), Node.js (Express), Java (Spring Boot), PHP (Laravel), Ruby (Rails), and Go (net/http, Gin, Echo). If your stack isn't listed, you can integrate directly with AgentAdmit's API.

Building or operating an MCP server? MCP server operators are app owners. Same SDKs, same pricing, same onboarding. The integration point is slightly different (JSON-RPC handler instead of HTTP middleware), but the token flow is identical. See the full MCP integration guide at agentadmit.com/docs/mcp-guide for STDIO and HTTP transport patterns, scope design for tools, and complete before/after code examples. The core operations are standard HTTP calls: POST to exchange tokens, POST to verify tokens via introspection, GET/DELETE for connection management. Any language that can make HTTP requests can integrate. See the API reference at agentadmit.com/docs for endpoint specs.

Q: What if I'm not using React? The backend SDK handles all server-side logic regardless of your frontend framework. For non-React frontends, you can build your own UI using the API endpoints the backend SDK creates. The endpoint contracts are documented in the API reference at agentadmit.com/docs.

Q: How does the agent know how to use my API? The self-describing token and request body schemas handle this automatically. When the agent exchanges the token, it receives a complete map of your endpoints, methods, and expected data structures. You don't need to provide separate API documentation to agents.

Q: What if a user wants to give their agent access to everything? That's their choice. AgentAdmit puts the user in control. They can select all scopes for full access, or start with read-only and expand later. Your job is to define the scopes. The user decides which ones to grant.

Q: What happens if an agent tries to access something outside its scopes? The SDK middleware blocks the request and returns a 403 error. Well-behaved agents tell the user which permission is missing so the user can update their access.

Q: Can I customize the look of the AgentAdmit page? Yes. Import the default styles with @agentadmit/react/styles.css or skip it and write your own. All CSS classes are prefixed with aa- (e.g., aa-panel, aa-btn-primary, aa-template-card). Override any class to match your app's design system.

Q: Can I use Claude Code, Codex, or another coding agent to do the integration for me? Yes. Any AI coding agent that can read files, install packages, and edit code can integrate AgentAdmit using this guide. Give the agent this document and your codebase. It will install the SDK, add middleware, set up the React component, and ask you for decisions like which scopes to define and what templates to write. See "Let Your AI Coding Agent Do the Integration" at the top of this guide.

Q: Why is introspection mandatory? Can I validate tokens locally for faster performance? No. Mandatory introspection is a core architectural decision. It ensures every agent action is validated, logged, and revocable in real time. Without it, there would be no centralized audit log, no way to detect abuse across apps, and no way to revoke a compromised agent's access everywhere at once. The latency impact is minimal (under 200ms) and only affects agent requests, never your regular user traffic.

Q: Does this affect my existing users who don't use AI agents? No. The SDK middleware only activates when an AgentAdmit token is present in the request. Regular user requests (login, browsing, using the app normally) pass through completely unaffected. Your existing auth system continues working exactly as before.

Q: How much does it cost? Test keys let you build and test at your own pace. Live keys require a subscription: Starter ($50/mo, 250K calls, $0.30/1K overage), Builder ($100/mo, 500K calls, $0.25/1K overage), or Pro ($200/mo, 1M calls, $0.20/1K overage). Enterprise plans are available for custom volume — contact us. If your usage grows beyond your current tier, upgrading gets you more included calls at a lower overage rate. Full pricing details at agentadmit.com/pricing.

Q: What's the difference between test and live keys? Functionality is identical. Same SDK, same endpoints, same flow. Test keys only work in your development environment. Live keys work in production. Swap the keys in your environment config. No code changes.

This guide is also available at agentadmit.com/docs/getting-started