{
  "openapi": "3.0.3",
  "info": {
    "title": "AgentPass API",
    "description": "Identity and permission layer for AI agents. Register agents, grant scoped permissions, check before every action, revoke instantly.",
    "version": "1.0.0",
    "contact": { "url": "https://agentpass.in" },
    "license": { "name": "Free to use" }
  },
  "servers": [{ "url": "https://agentpass.in", "description": "Production" }],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Agent secret key (sk_ap_xxx)"
      },
      "SessionCookie": {
        "type": "apiKey",
        "in": "cookie",
        "name": "ap_session",
        "description": "JWT session cookie set after magic link sign-in"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string" },
          "message": { "type": "string" },
          "docs": { "type": "string", "format": "uri" }
        }
      },
      "Agent": {
        "type": "object",
        "properties": {
          "agent_id": { "type": "string", "example": "ap_x9k2f3a8b1c4d5e6" },
          "name": { "type": "string" },
          "description": { "type": "string" },
          "status": { "type": "string", "enum": ["active", "suspended", "revoked"] },
          "metadata": { "type": "object", "nullable": true },
          "created_at": { "type": "string", "format": "date-time" },
          "last_seen": { "type": "string", "format": "date-time" }
        }
      },
      "Permission": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "agent_id": { "type": "string" },
          "action": { "type": "string" },
          "granted_by": { "type": "string", "format": "email" },
          "granted_at": { "type": "string", "format": "date-time" },
          "expires_at": { "type": "string", "format": "date-time", "nullable": true },
          "revoked_at": { "type": "string", "format": "date-time", "nullable": true },
          "revoked_by": { "type": "string", "nullable": true },
          "status": { "type": "string", "enum": ["active", "expired", "revoked"] },
          "scope": { "type": "object", "nullable": true },
          "metadata": { "type": "object", "nullable": true }
        }
      }
    }
  },
  "paths": {
    "/agent/register": {
      "post": {
        "summary": "Register a new AI agent",
        "description": "Creates a new agent identity. Returns agent_id and secret key. The secret is shown ONCE — store it immediately.",
        "operationId": "registerAgent",
        "tags": ["Agents"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name", "developer_email"],
                "properties": {
                  "name": { "type": "string", "maxLength": 100, "example": "my-booking-agent" },
                  "description": { "type": "string", "example": "Books flights for users" },
                  "developer_email": { "type": "string", "format": "email", "example": "dev@example.com" },
                  "metadata": { "type": "object" }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Agent registered",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agent_id": { "type": "string", "example": "ap_x9k2f3a8b1c4d5e6" },
                    "secret": { "type": "string", "example": "sk_ap_4f9a2b3c..." },
                    "docs_url": { "type": "string" },
                    "dashboard_url": { "type": "string" },
                    "note": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "description": "Rate limited" }
        }
      }
    },
    "/agent/{agent_id}": {
      "get": {
        "summary": "Get agent profile",
        "operationId": "getAgent",
        "tags": ["Agents"],
        "security": [{ "BearerAuth": [] }],
        "parameters": [{ "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": { "description": "Agent profile", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/Agent" }, { "properties": { "active_permissions": { "type": "array", "items": { "$ref": "#/components/schemas/Permission" } } } }] } } } },
          "401": { "description": "Unauthorized" },
          "403": { "description": "Forbidden" }
        }
      }
    },
    "/agent/{agent_id}/permissions": {
      "get": {
        "summary": "List all permissions for an agent",
        "operationId": "getAgentPermissions",
        "tags": ["Agents"],
        "security": [{ "BearerAuth": [] }, { "SessionCookie": [] }],
        "parameters": [{ "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": { "description": "Permissions list", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string" }, "permissions": { "type": "array", "items": { "$ref": "#/components/schemas/Permission" } } } } } } }
        }
      }
    },
    "/permission/check": {
      "get": {
        "summary": "Check if agent is authorized for an action",
        "description": "Call this before every consequential action. Target latency <50ms.",
        "operationId": "checkPermission",
        "tags": ["Permissions"],
        "security": [{ "BearerAuth": [] }],
        "parameters": [
          { "name": "agent_id", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "action", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Permission check result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "allowed": { "type": "boolean" },
                    "granted_by": { "type": "string", "nullable": true },
                    "expires_at": { "type": "string", "format": "date-time", "nullable": true },
                    "scope": { "type": "object", "nullable": true },
                    "reason": { "type": "string", "nullable": true },
                    "latency_ms": { "type": "integer" }
                  }
                }
              }
            }
          },
          "401": { "description": "Unauthorized" },
          "429": { "description": "Rate limited" }
        }
      }
    },
    "/permission/grant": {
      "post": {
        "summary": "Grant a permission to an agent",
        "description": "Requires human session cookie from magic link sign-in.",
        "operationId": "grantPermission",
        "tags": ["Permissions"],
        "security": [{ "SessionCookie": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["agent_id", "action"],
                "properties": {
                  "agent_id": { "type": "string" },
                  "action": { "type": "string", "example": "book_flight" },
                  "expires_in": { "type": "string", "example": "7d", "description": "Format: Nd, Nh, Nm, Ns" },
                  "scope": { "type": "object", "description": "Optional resource constraints" },
                  "metadata": { "type": "object" }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Permission granted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Permission" } } } },
          "401": { "description": "Unauthorized" },
          "404": { "description": "Agent not found" }
        }
      }
    },
    "/permission/revoke": {
      "post": {
        "summary": "Revoke a permission immediately",
        "operationId": "revokePermission",
        "tags": ["Permissions"],
        "security": [{ "SessionCookie": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "agent_id": { "type": "string" },
                  "action": { "type": "string" },
                  "permission_id": { "type": "string", "format": "uuid" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean" }, "revoked_at": { "type": "string", "format": "date-time" }, "count": { "type": "integer" } } } } } },
          "401": { "description": "Unauthorized" },
          "404": { "description": "Permission not found" }
        }
      }
    },
    "/auth/magic-link": {
      "post": {
        "summary": "Send a magic link sign-in email",
        "operationId": "sendMagicLink",
        "tags": ["Auth"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "type": "object", "required": ["email"], "properties": { "email": { "type": "string", "format": "email" } } }
            }
          }
        },
        "responses": {
          "200": { "description": "Email sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }
        }
      }
    },
    "/auth/verify": {
      "get": {
        "summary": "Verify magic link token and start session",
        "operationId": "verifyMagicLink",
        "tags": ["Auth"],
        "parameters": [{ "name": "token", "in": "query", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "302": { "description": "Redirect to /dashboard with session cookie set" },
          "400": { "description": "Invalid or expired token" }
        }
      }
    },
    "/health": {
      "get": {
        "summary": "Health check",
        "operationId": "health",
        "tags": ["Utility"],
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "version": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } }
        }
      }
    },
    "/stats": {
      "get": {
        "summary": "Live platform statistics",
        "operationId": "stats",
        "tags": ["Utility"],
        "responses": {
          "200": { "description": "Stats", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents_registered": { "type": "integer" }, "permissions_granted": { "type": "integer" }, "checks_today": { "type": "integer" }, "checks_total": { "type": "integer" } } } } } }
        }
      }
    }
  },
  "tags": [
    { "name": "Agents", "description": "Register and manage AI agent identities" },
    { "name": "Permissions", "description": "Grant, check, and revoke permissions" },
    { "name": "Auth", "description": "Magic link authentication for humans" },
    { "name": "Utility", "description": "Health and stats endpoints" }
  ]
}