# AgentPass — Identity & Permission Layer for AI Agents
# https://agentpass.in
# This file is written for AI agents. Read it and start using the API immediately.

## What is AgentPass?

AgentPass is the identity and permission layer for AI agents.
- Every AI agent gets a verified, persistent identity (an AgentPass ID).
- Humans grant scoped, expiring, revocable permissions to agents.
- Services call AgentPass before letting an agent act — one call, instant yes/no.
- Think of it as OAuth, but built for AI agents instead of humans.
- It is completely free. No payments, no trials, no rate limit tiers.

## Base URL

https://agentpass.in

All responses are JSON. CORS is open to all origins.

## Authentication

Two methods:

1. Agent secret key — Bearer token in Authorization header.
   Used for: /permission/check, /agent/:id, /agent/:id/permissions
   Format: Authorization: Bearer sk_ap_xxxxx

2. Session cookie (ap_session) — Set after magic link sign-in.
   Used for: /permission/grant, /permission/revoke, /dashboard/data
   Humans sign in via POST /auth/magic-link → GET /auth/verify?token=xxx

---

## ENDPOINTS

### POST /agent/register
Register a new AI agent. Returns an agent_id and secret key.
The secret key is returned ONCE and never stored in plaintext. Store it immediately.

Request:
  Content-Type: application/json
  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"
  }

Rate limit: 10 requests per IP per hour.

---

### GET /permission/check
Check if an agent is authorized to perform an action.
CALL THIS BEFORE EVERY CONSEQUENTIAL ACTION.
Target latency: <50ms.

Request:
  Authorization: Bearer sk_ap_xxxxx
  Query params:
    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
  }

Rate limit: 1000 requests per agent per minute.

---

### POST /permission/grant
Grant a permission to an agent. Requires human session (magic link login).

Request:
  Cookie: ap_session=<jwt>
  Content-Type: application/json
  Body: {
    "agent_id": "ap_xxx" (required),
    "action": "book_flight" (required),
    "expires_in": "7d" (optional — formats: Nd, Nh, Nm, Ns),
    "scope": { "max_spend": 500 } (optional — resource constraints),
    "metadata": {} (optional)
  }

Response 201:
  {
    "permission_id": "550e8400-e29b-41d4-a716-446655440000",
    "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. Effect is instant on next /permission/check call.

Request:
  Cookie: ap_session=<jwt>
  Content-Type: application/json
  Body (either form):
    { "agent_id": "ap_xxx", "action": "book_flight" }
    OR
    { "permission_id": "550e8400-..." }

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

---

### GET /agent/:agent_id
Get agent profile and active permissions. Auth: Bearer secret key.
Also updates the agent's last_seen timestamp.

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

---

### GET /agent/:agent_id/permissions
Get all permissions for an agent (active, expired, revoked).
Auth: Bearer secret key OR session cookie.

Response:
  {
    "agent_id": "ap_xxx",
    "permissions": [
      {
        "id": "uuid",
        "agent_id": "ap_xxx",
        "action": "book_flight",
        "granted_by": "user@example.com",
        "granted_at": "2026-05-01T00:00:00Z",
        "expires_at": "2026-05-08T00:00:00Z",
        "revoked_at": null,
        "status": "active",
        "scope": null
      }
    ]
  }

---

### POST /auth/magic-link
Send a magic link sign-in email to a human.

Request:
  Content-Type: application/json
  Body: { "email": "user@example.com" }

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

Rate limit: 5 requests per email per 15 minutes.

---

### GET /auth/verify?token=xxx
Validate a magic link token. Sets ap_session cookie. Redirects to /dashboard.
Tokens expire in 15 minutes. Single-use.

---

### GET /health
Public health check. No auth required.

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

---

### GET /stats
Live platform stats. No auth required.

Response:
  {
    "agents_registered": 42,
    "permissions_granted": 187,
    "checks_today": 3021,
    "checks_total": 48293,
    "timestamp": "2026-05-03T09:00:00Z"
  }

---

## ERROR FORMAT

All errors follow this structure:
  {
    "error": "error_code",
    "message": "Human readable description",
    "docs": "https://agentpass.in/docs#error_code"
  }

Error codes:
  unauthorized         — 401 — Missing or invalid credentials
  forbidden            — 403 — Authenticated but access denied
  not_found            — 404 — Resource does not exist
  missing_fields       — 400 — Required fields missing from body
  missing_params       — 400 — Required query parameters missing
  invalid_email        — 400 — Email format invalid
  invalid_name         — 400 — Agent name too long (max 100 chars)
  agent_not_found      — 404 — No active agent with given ID
  permission_not_found — 404 — No active permission matching criteria
  rate_limited         — 429 — Too many requests
  server_error         — 500 — Internal error

---

## RATE LIMITS

  /agent/register      10 req / hour   per IP
  /permission/check    1000 req / min  per agent_id
  /auth/magic-link     5 req / 15min   per email

---

## QUICK START (for AI agents)

1. Register yourself:
   POST /agent/register
   { "name": "my-agent", "developer_email": "dev@example.com" }
   → Save agent_id and secret immediately.

2. Before any consequential action, check permission:
   GET /permission/check?agent_id=ap_xxx&action=your_action
   Authorization: Bearer sk_ap_xxx
   → If allowed=false, do NOT proceed.

3. To get permissions, a human must:
   a. Sign in via POST /auth/magic-link + GET /auth/verify
   b. POST /permission/grant with their session cookie

---

## MCP SERVER

AgentPass exposes an MCP server (Model Context Protocol) for direct AI integration.
Discovery: https://agentpass.in/.well-known/mcp.json
Run: node mcp-server.js (stdio transport, JSON-RPC 2.0)

Tools: register_agent, check_permission, grant_permission, revoke_permission, get_agent_status

---

## SECURITY NOTES

- Secret keys are bcrypt-hashed (cost 12) before storage. Never stored in plaintext.
- Magic link tokens: 32 random bytes, expire 15 min, single-use.
- Row Level Security enforced on all database tables.
- All API responses include security headers.

---

## OPENAPI SPEC

Full OpenAPI 3.0 specification: https://agentpass.in/openapi.json
AI plugin manifest: https://agentpass.in/.well-known/ai-plugin.json

---

AgentPass · https://agentpass.in · Built in India