API documentation

Machine-readable: /openapi.json · /llms.txt · /.well-known/agent-secret-lease.json. All agent responses are JSON.

Model

• Secret — a credential the owner stored (bearer token, API-key header, API-key query parameter, basic auth or a custom header). Encrypted at rest; never returned.
• Agent — an identity with its own token (asl_agent_…, shown once; only a hash is stored).
• Policy — what one agent may do with one secret: hosts, methods, path prefixes, maximum lease length, requests per lease, optional total limit and expiry.
• Lease — a short-lived permission on a policy. Status: pending, active, expired, revoked, exhausted. Expiry is computed when the lease is read or used.

Agent flow

GET  https://agentsecretlease.online/api/v1/capabilities          # policies you may lease, next lease price
POST https://agentsecretlease.online/api/v1/leases                # Idempotency-Key required
     {"policy_id":"pol_…","duration_seconds":300,"max_requests":10}
POST https://agentsecretlease.online/api/v1/leases/{id}/execute   # one proxied HTTPS request
     {"method":"POST","url":"https://api.openai.com/v1/responses",
      "headers":{"Accept":"application/json"},"body":{"model":"…","input":"…"}}
GET  https://agentsecretlease.online/api/v1/leases/{id}            # status, remaining requests
POST https://agentsecretlease.online/api/v1/leases/{id}/revoke     # release early

Execute returns {"lease":{…},"upstream":{"status":200,"headers":{…},"body":"…","body_encoding":"utf8","redactions":0}}. The HTTP status is 200 whenever the upstream answered; read upstream.status.

Payment (x402)

Each owner’s plan includes a monthly free lease allowance. After that, a lease costs 0.01 USDC on Base (x402 v2, exact scheme). Without payment, POST /api/v1/leases answers 402 with the requirement in the body (x402) and in the PAYMENT-REQUIRED header. Sign it, then resend the identical body and Idempotency-Key with PAYMENT-SIGNATURE. The settlement comes back in PAYMENT-RESPONSE. Every policy check runs before payment, so a rejected request is never charged; one payment authorization buys exactly one lease.

Security rules enforced by the proxy

• https only, default port, DNS hostnames only; the host must be on the policy’s list (exact match).
• Every resolved address is checked when the connection opens: loopback, private, CGNAT, link-local and metadata (169.254.169.254) and reserved ranges are refused.
• Redirects are never followed (UPSTREAM_REDIRECT_BLOCKED).
• Path prefixes match on segment boundaries; encoded slashes, encoded dots and empty segments are refused.
• Agents cannot set Authorization, Cookie, Host, Proxy-*, X-Forwarded-*, Accept-Encoding or the credential’s header.
• Responses: at most 1 MB; only safe headers are passed back; any echo of the credential is replaced by [REDACTED].
• The current policy is checked on every request; tightening or revoking it affects active leases immediately.

MCP

POST https://agentsecretlease.online/api/mcp (Streamable HTTP, stateless JSON-RPC) with the same bearer token. Tools: list_capabilities, request_lease, get_lease, execute_with_lease, revoke_lease.

Errors

{"error":{"code":"LEASE_EXPIRED","message":"The lease has expired.","retryable":false}}

Codes: UNAUTHORIZED, FORBIDDEN, AGENT_REVOKED, SECRET_NOT_FOUND, POLICY_NOT_FOUND, POLICY_DENIED, LEASE_NOT_FOUND, LEASE_PENDING, LEASE_EXPIRED, LEASE_REVOKED, LEASE_EXHAUSTED, HOST_NOT_ALLOWED, METHOD_NOT_ALLOWED, PATH_NOT_ALLOWED, DESTINATION_BLOCKED, PLAN_LIMIT_REACHED, PAYMENT_REQUIRED, PAYMENT_FAILED, PAYMENT_UNAVAILABLE, IDEMPOTENCY_KEY_REQUIRED, IDEMPOTENCY_CONFLICT, DUPLICATE_REQUEST, RATE_LIMITED, PAYLOAD_TOO_LARGE, UPSTREAM_ERROR, UPSTREAM_TIMEOUT, UPSTREAM_REDIRECT_BLOCKED, UPSTREAM_RESPONSE_TOO_LARGE, VALIDATION_ERROR, SERVICE_UNAVAILABLE.

Owner API

The dashboard uses the same REST API with a session cookie: /api/v1/agents, /api/v1/secrets, /api/v1/policies, /api/v1/leases, /api/v1/audit. See the OpenAPI document for every field.