AgentPass documentation

AgentPass is runtime identity and authorization infrastructure for autonomous AI agents. Traditional IAM answers whether an identity is authentic. AgentPass answers a different question: may this agent perform this action, on this resource, under these circumstances, right now.

Your agent calls AgentPass before it acts. AgentPass resolves identity, verifies the Agent Passport, evaluates policy against the request context, and returns exactly one decision: ALLOW, MODIFY, DENY or ESCALATE. Every decision is stored with its reasoning and an audit event.

Core concepts

Agent: A registered autonomous actor with a name, type, owner and environment. Identified by agt_…
Agent Passport: The AgentPass identity object for one agent: ap_…, its capability set, validity window and status. Ours, not an industry standard.
Policy: A rule with a scope (action, resource type, agent type), conditions, an effect and a priority. Lowest priority number wins.
Authorization request: What the agent wants to do: action, resource and context.
Decision: Exactly one of ALLOW, MODIFY, DENY or ESCALATE, with a reason, the matched policy and any modifications.
Approval: A human decision required by a policy that escalated, or modified a request and left a remainder.
Audit event: An immutable-by-policy record of something meaningful, carrying a SHA-256 digest of its payload.

Quick start

1. Create an account and an organization.
2. Register your agent under Agents.
3. Issue its passport with the capabilities it may request.
4. Create a policy for the action.
5. Create an API key under Developers.
6. Call the authorization endpoint before acting.
7. Inspect the decision, approval and audit event in the console.

API authentication

Send your API key as a bearer token. The key resolves the organization on the server — requests never supply an organization id. Keys are stored as a SHA-256 hash; the secret is shown once at creation and cannot be retrieved afterwards.

Authorization: Bearer apk_live_...
Content-Type: application/json

Authorization API

POST https://your-app.lovable.app/api/public/v1/authorize

{
  "agent_id": "agt_7f92a1c4b8de",
  "action": "execute_payment",
  "resource": { "type": "payment", "vendor_id": "vendor_abc", "amount": 18400, "currency": "USD" },
  "context": { "environment": "production", "autonomous": true }
}

Response (example of the MODIFY path):

{
  "decision_id": "dec_4c1f88a2d0b7",
  "decision": "MODIFY",
  "reason": "Autonomous payment limit exceeded — capped at $10,000, remainder requires human approval.",
  "code": "policy_modify",
  "policy": { "id": "…", "name": "Autonomous Payment Limit" },
  "modifications": {
    "maximum_allowed_amount": 10000,
    "requires_approval_for_remaining": 8400,
    "requires_human_approval": true
  },
  "audit_event_id": "evt_1b9d77c3e5a4",
  "approval_request_id": "…",
  "latency_ms": 24
}

latency_ms is the measured evaluation time for that request on the serving instance. It is not a performance guarantee.

Decision types

ALLOW: Proceed as requested.
MODIFY: Proceed only within the returned modifications — for example a capped amount. A remainder may require approval.
ESCALATE: Do not act. A human must approve first; an approval request has been created.
DENY: Do not act. The reason explains which check or policy refused.

Policy examples

Autonomous payment limit
  agent type   Procurement Agent
  action       execute_payment on payment
  ALLOW        resource.amount lte 10000        (priority 10)
  MODIFY       resource.amount gt 10000         (priority 20)
               max_amount 10000, requires_human_approval

Refund approval limit
  agent type   Customer Support Agent
  ALLOW        resource.amount lte 500          (priority 10)
  ESCALATE     resource.amount gt 500           (priority 20)

Production database protection
  any agent type
  DENY         context.environment eq production (priority 1)
               action delete_database on database

Error handling

AgentPass fails closed. When authorization cannot be safely determined the answer is DENY with a machine-readable code.

401 missing_credentials      no bearer token
401 invalid_credentials      key unknown or revoked
400 invalid_request          malformed body
403 DENY unknown_agent       no such agent in this organization
403 DENY agent_not_active    agent suspended or revoked
403 DENY no_passport         no passport issued
403 DENY passport_revoked    passport revoked
403 DENY passport_expired    passport past its validity window
403 DENY capability_missing  action not in the passport capability set
403 DENY missing_context     required context absent or not comparable
403 DENY no_applicable_policy no policy matched — default deny
500 evaluation_failed        evaluation error; treat as DENY

Security model

Every record belongs to one organization and is protected by database row-level security.
Console reads run as the signed-in user; writes check organization role on the server.
The authorization endpoint derives the organization from the API key, never from the request body.
API keys are stored only as SHA-256 hashes and can be revoked.
Audit payloads carry a SHA-256 digest so a stored record can be checked for tampering.
Decisions are append-only through the service; the console cannot write or edit them.

AgentPass holds no security or compliance certification. Nothing in this documentation should be read as a certification claim.