API Reference

AgentPass base URL: https://agentpass.in
All responses are application/json. CORS is open to all origins.

Quickstart

Three steps to add identity and permission checking to any AI agent:

Step 1 — Register your agent

curl -X POST https://agentpass.in/agent/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-booking-agent",
    "description": "Books flights for users",
    "developer_email": "you@example.com"
  }'

# Response — save the secret, it's shown ONCE
{
  "agent_id": "ap_x9k2f3a8b1c4d5e6",
  "secret": "sk_ap_4f9a2b3c8d1e...",
  "docs_url": "https://agentpass.in/docs",
  "note": "Save your secret — shown once only"
}

Step 2 — Human grants permission (from dashboard or API)

curl -X POST https://agentpass.in/permission/grant \
  -H "Content-Type: application/json" \
  -H "Cookie: ap_session=<session_token>" \
  -d '{
    "agent_id": "ap_x9k2f3a8b1c4d5e6",
    "action": "book_flight",
    "expires_in": "7d"
  }'

Step 3 — Agent checks before acting

curl "https://agentpass.in/permission/check?agent_id=ap_x9k2f3a8b1c4d5e6&action=book_flight" \
  -H "Authorization: Bearer sk_ap_4f9a2b3c8d1e..."

# Response
{ "allowed": true, "granted_by": "user@example.com", "expires_at": "2026-05-10T00:00:00Z", "latency_ms": 12 }

Authentication

AgentPass uses two authentication methods:

Agent secret key — Bearer token in Authorization header. Used by AI agents calling /permission/check and /agent/:id. Format: Bearer sk_ap_xxx
Session cookie — Set automatically after magic link sign-in. Used for /permission/grant, /permission/revoke, and the dashboard. Cookie name: ap_session

POST /agent/register

Register a new AI agent. Returns an agent_id and secret. The secret is returned once only and never stored in plaintext.

POST /agent/register Public · Rate limited 10/hour per IP

Request body

{
  "name": "string (required, max 100 chars)",
  "description": "string (optional)",
  "developer_email": "string (required, valid email)",
  "metadata": "object (optional)"
}

Response 201

{
  "agent_id": "ap_x9k2f3a8b1c4d5e6",
  "secret": "sk_ap_4f9a2b3c8d1e7f6a5b4c3d2e1f...",
  "docs_url": "https://agentpass.in/docs",
  "dashboard_url": "https://agentpass.in/dashboard",
  "note": "Save your secret — shown once only"
}

Code examples

curl -X POST https://agentpass.in/agent/register \
  -H "Content-Type: application/json" \
  -d '{"name":"my-agent","description":"Does tasks","developer_email":"you@example.com"}'

import requests

resp = requests.post("https://agentpass.in/agent/register", json={
    "name": "my-agent",
    "description": "Does tasks",
    "developer_email": "you@example.com"
})
data = resp.json()
print(data["agent_id"])  # Save this
print(data["secret"])    # Save this — shown once!

const resp = await fetch("https://agentpass.in/agent/register", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "my-agent",
    description: "Does tasks",
    developer_email: "you@example.com"
  })
});
const { agent_id, secret } = await resp.json();
// Save secret — shown once!

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    body, _ := json.Marshal(map[string]string{
        "name": "my-agent",
        "description": "Does tasks",
        "developer_email": "you@example.com",
    })
    resp, _ := http.Post("https://agentpass.in/agent/register",
        "application/json", bytes.NewBuffer(body))
    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println(result["agent_id"])
    fmt.Println(result["secret"]) // Save once!
}

GET /permission/check

Check if an agent is authorized to perform an action. Call this before every consequential action. Target response time: <50ms.

GET /permission/check Auth: Bearer secret key · 1000/min per agent

Query parameters

agent_id=ap_xxx   (required)
action=book_flight (required)

Response — allowed

{
  "allowed": true,
  "granted_by": "user@example.com",
  "expires_at": "2026-05-10T00:00:00Z",
  "scope": null,
  "latency_ms": 12
}

Response — denied

{
  "allowed": false,
  "reason": "Permission denied or expired",
  "latency_ms": 8
}

curl "https://agentpass.in/permission/check?agent_id=ap_xxx&action=book_flight" \
  -H "Authorization: Bearer sk_ap_..."

import requests

r = requests.get(
    "https://agentpass.in/permission/check",
    params={"agent_id": "ap_xxx", "action": "book_flight"},
    headers={"Authorization": "Bearer sk_ap_..."}
)
result = r.json()
if result["allowed"]:
    # proceed
    pass
else:
    raise PermissionError(result.get("reason"))

const r = await fetch(
  `https://agentpass.in/permission/check?agent_id=${agentId}&action=book_flight`,
  { headers: { Authorization: `Bearer ${secretKey}` } }
);
const { allowed, reason } = await r.json();
if (!allowed) throw new Error(reason);

req, _ := http.NewRequest("GET",
    "https://agentpass.in/permission/check?agent_id=ap_xxx&action=book_flight", nil)
req.Header.Set("Authorization", "Bearer sk_ap_...")
resp, _ := http.DefaultClient.Do(req)
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
if result["allowed"] != true {
    panic(result["reason"])
}

POST /permission/grant

Grant a permission to an agent. Requires a valid human session (from magic link sign-in).

POST /permission/grant Auth: Session cookie

Request body

{
  "agent_id": "ap_xxx",         // required
  "action": "book_flight",      // required
  "expires_in": "7d",           // optional: 7d, 24h, 30m, 60s
  "scope": { "max_spend": 500 },// optional: resource constraints
  "metadata": {}                // optional
}

Response 201

{
  "permission_id": "550e8400-...",
  "agent_id": "ap_xxx",
  "action": "book_flight",
  "granted_by": "user@example.com",
  "expires_at": "2026-05-10T00:00:00Z"
}

POST /permission/revoke

Revoke a permission immediately. Takes effect on the next /permission/check call.

POST /permission/revoke Auth: Session cookie

Request body (either form works)

// By agent + action
{ "agent_id": "ap_xxx", "action": "book_flight" }

// By permission UUID
{ "permission_id": "550e8400-..." }

Response 200

{ "revoked": true, "revoked_at": "2026-05-03T09:00:00Z", "count": 1 }

POST /auth/magic-link

POST /auth/magic-link Public · 5 req/15min per email

// Request
{ "email": "you@example.com" }

// Response
{ "message": "Check your email for a sign-in link." }

GET /auth/verify

GET /auth/verify?token=xxx

Validates the magic link token, sets a session cookie, and redirects to /dashboard. Tokens expire in 15 minutes and can only be used once.

GET /agent/:agent_id

GET /agent/:agent_id Auth: Bearer secret key

{
  "agent_id": "ap_xxx",
  "name": "my-booking-agent",
  "description": "Books flights",
  "status": "active",
  "created_at": "2026-05-01T00:00:00Z",
  "last_seen": "2026-05-03T09:00:00Z",
  "active_permissions": [ ... ]
}

GET /health

{ "status": "ok", "version": "1.0.0", "timestamp": "2026-05-03T09:00:00Z" }

GET /stats

{
  "agents_registered": 42,
  "permissions_granted": 187,
  "checks_today": 3021,
  "checks_total": 48293
}

Error codes

All errors follow: { "error": "code", "message": "human readable", "docs": "url" }

Code	HTTP	Meaning
unauthorized	401	Missing or invalid credentials
forbidden	403	Authenticated but not allowed for this resource
not_found	404	Resource does not exist
missing_fields	400	Required fields missing from request body
missing_params	400	Required query parameters missing
invalid_email	400	Email address is not valid format
invalid_name	400	Agent name exceeds 100 characters
agent_not_found	404	No active agent found with given ID
permission_not_found	404	No active permission matching criteria
rate_limited	429	Too many requests
server_error	500	Internal server error

Rate limits

Endpoint	Limit	Window
/agent/register	10 requests	per IP per hour
/permission/check	1,000 requests	per agent per minute
/auth/magic-link	5 requests	per email per 15 minutes

MCP Server

AgentPass exposes an MCP (Model Context Protocol) server for AI agents to auto-connect. Discovery file: /.well-known/mcp.json

Connect via stdio

node mcp-server.js

Available tools

register_agent    — Register a new agent
check_permission  — Check if action is allowed (call before every action)
grant_permission  — Grant a permission (requires human session)
revoke_permission — Revoke a permission immediately
get_agent_status  — Get agent profile and active permissions

Claude Desktop config

{
  "mcpServers": {
    "agentpass": {
      "command": "node",
      "args": ["/path/to/agentpass/mcp-server.js"],
      "env": { "BASE_URL": "https://agentpass.in" }
    }
  }
}

Security model

Secret keys are bcrypt-hashed (cost 12) before storage. The plaintext is never stored.
A SHA-256 index of the secret enables O(1) lookup before the full bcrypt comparison.
Magic link tokens are 32 random bytes (256 bits of entropy), expire in 15 minutes, single-use.
Session cookies are HttpOnly, Secure, SameSite=Lax, JWT-signed.
Row Level Security is enabled on all Supabase tables. Direct client access is blocked.
All inputs are validated server-side. Parameterized queries prevent SQL injection.
Security headers on every response: X-Content-Type-Options, X-Frame-Options, Strict-Transport-Security.

OpenAPI spec

Full OpenAPI 3.0 specification available at /openapi.json.

AI agents: read /llms.txt for a plain-text description of all endpoints.