§ DEV · BUILD · AGENT-ACTION LAYER

Build with the agent-action layer.

Three endpoints, one mental model. Drop-in SDKs for OpenAI Agent SDK, ChatGPT Agent Mode, Claude Desktop, and any Model Context Protocol client.

5-minute quickstart Swagger UI ↗ Speak with Paphwey ↗

OpenAI Agent SDK ChatGPT Agent Mode Claude Desktop Anthropic MCP Python / TypeScript

§ 01 · Quickstart Three steps

From zero to verified action

Three calls. One approval on the phone. A signed outcome.

API keys stay server-side. Mount these calls from your backend; the phone handles the approval. The five-minute quickstart walks the full hello-world end-to-end with cURL; full reference and response shapes live in /api/docs/.

Create a delegation

Grant the agent a scoped authority — scopes, ceiling, expiry, challenge types it can open.

curl -X POST https://www.paphwey.com/api/v1/agent/delegations \
  -H "X-API-Key: sk_live_abcd.deadbeef..." \
  -H "Content-Type: application/json" \
  -d '{
    "principal_email": "alice@example.com",
    "provider": "openai",
    "agent_id": "shopping-agent",
    "allowed_scopes": ["purchase"],
    "allowed_challenge_types": ["HIGH_VALUE_PURCHASE_REQUIRED"],
    "max_amount_minor": 2500,
    "currency": "GBP",
    "valid_until": "2026-05-01T00:00:00Z"
  }'

Present the delegation

Open a challenge tied to the delegation; surface the returned approval_url to the user's phone.

from paphwey import PaphweyClient

paphwey = PaphweyClient(
    base_url="https://www.paphwey.com",
    api_key="sk_live_abcd.deadbeef...",
)

challenge = paphwey.present_delegation(
    delegation_id=delegation.delegation_id,
    challenge_type="HIGH_VALUE_PURCHASE_REQUIRED",
    audience="merchant.example",
    payload={
        "action_context": {
            "scope": "purchase",
            "amount_minor": 1500,
            "currency": "GBP",
        },
        "minimum_assurance": 10,
    },
)
print(challenge.approval_url)

Verify the outcome

When the user approves, the RP receives a signed attestation JWT. Verify it locally or via the gateway.

import { PaphweyAgentClient } from "@paphwey/web-sdk/server";

const paphwey = new PaphweyAgentClient({
  baseUrl: process.env.PAPHWEY_BASE_URL,
  apiKey: process.env.PAPHWEY_API_KEY
});

const outcome = await paphwey.verifyOutcome({
  attestationToken: token,
  audience: "merchant.example",
  expectedDelegationId: delegation.delegation_id
});
if (!outcome.valid) throw new Error("Attestation rejected");

§ 02 · MCP server Anthropic · OpenAI · ChatGPT

paphwey-mcp

Drop a Paphwey tool set into any MCP-speaking agent runtime.

The paphwey-mcp Python package is a stdio MCP server that exposes five first-class tools — create_delegation, present_delegation, verify_outcome, list_policies, and revoke_delegation — with the same field names as the REST API and the Python SDK.

Install

One pip install, one config snippet.

pip install paphwey-mcp

Drop this into claude_desktop_config.json:

{
  "mcpServers": {
    "paphwey": {
      "command": "paphwey-mcp",
      "env": {
        "PAPHWEY_API_KEY": "sk_live_...",
        "PAPHWEY_BASE_URL": "https://www.paphwey.com"
      }
    }
  }
}

Works with

Every major agent runtime.

Claude Desktop — reads the stdio config above.
ChatGPT Agent Mode — same mcpServers shape.
OpenAI Agent SDK — launch via StdioServerParameters.
Any MCP client — stdio-only in v1, HTTP transport in v2.
Error envelopes are scrubbed before surfacing to the agent — no PII leakage.

§ 03 · SDKs & references Everything you need

5-minute quickstart

The shortest path from API key to verified attestation. cURL only — pre-flight, mint, approve, verify, common errors.

Open the quickstart ↗

REST API guide

Step-by-step integration over HTTP. Auth, triad, webhooks, errors, pre-ship checklist. Any language, any stack.

Open the REST guide ↗

Python SDK guide

Step-by-step integration with paphwey — sync + async clients, FastAPI, Django, Celery patterns.

Open the Python guide ↗

Web SDK guide

Step-by-step integration with @paphwey/web-sdk — Node, Next.js, Express, Bun, Deno, Workers, Edge.

Open the Web guide ↗

MCP server guide

Step-by-step wiring for Claude Desktop, ChatGPT Agent Mode, OpenAI Agent SDK, Cursor, and custom MCP clients.

Open the MCP guide ↗

Agent API reference

One-page REST reference for the agent-action triad — shapes, errors, rate limits. Mounted at /api/v1/agent/.

Swagger UI ↗

OpenAPI schema

Machine-readable contract for code generation or your own client. Regenerated on every release.

/api/schema/

§ 04 · Security notes Read before you ship

Non-negotiables

Four invariants we enforce on your behalf.

These are the guarantees that make the attestation meaningful. Keep them in mind when you wire Paphwey into your product.

API keys stay server-side

Never ship an sk_live_... key into the browser or into the agent's tool input.

Detection ≠ decision

Agent detection is heuristic. The decision to require verification lives in your policy and the challenge type — not the client.

Verify on every request

Never trust an attestation claim you haven't re-verified against the gateway JWKS on the current request.

Pin the agent key

For key-bound delegations, pin the cnfJwk you receive from verify_outcome for the whole session.

Ready to build

Five minutes to your first verified agent action.

Open API docs Talk to the team ↗