Developers / typed authority

One call before the agent acts.

Authenticate the agent once, describe the exact requested action and let CAPYN return the only three outcomes your integration needs.

Run the local demo Inspect demo credentials

agent.ts typed contract

import { Capyn } from "@capyn/sdk";

const capyn = new Capyn({
  apiKey: process.env.CAPYN_API_KEY!
});

const result = await capyn.authorize({
  capability: "spend.compute",
  amount: {
    value: "18.42",
    currency: "USD"
  },
  vendor: { id: "openai" },
  metadata: {
    purpose: "Purchase inference capacity"
  }
});

if (result.decision === "ALLOW") {
  // Continue with this exact action.
}

Twenty-second quick start

See the policy engine decide.

The demo runs in memory and exercises the real Fastify handlers, identity adapter and policy engine. No database service is required.

Node.js 22+Corepackpnpm 11

terminal typed contract

corepack pnpm install
corepack pnpm demo

$18 → OpenAIALLOW

$30 → UnknownDENY

$120 → AWSREQUIRE_APPROVAL

transfer.walletDENY

REST API / v1

A small surface with explicit contracts.

Agent identity always comes from the bearer key. `agentId` is not accepted in the authorization payload.

Understand the trust boundary

GET/v1/me

Resolve the authenticated agent identity.

GET/v1/mandate

Inspect the agent's current active authority.

POST/v1/authorize

Request a decision for one consequential action.

GET/v1/authorizations/:id

Retrieve the request, decision and policy trace.

POST/v1/authorizations/:id/execute

Execute one valid authorization through the configured adapter.

Deterministic response

Branch on the decision. Log the evidence.

Reason codes are safe for machines, support tooling and audit views. Human-readable descriptions stay available without replacing the canonical code.

ALLOW

{
  "decision": "ALLOW",
  "authorizationId": "auth_12928",
  "reasonCodes": [
    "CAPABILITY_ALLOWED",
    "VENDOR_ALLOWED",
    "DAILY_LIMIT_OK"
  ]
}

DENY

{
  "decision": "DENY",
  "authorizationId": "auth_90411",
  "reasonCodes": [
    "VENDOR_NOT_ALLOWED"
  ]
}

REQUIRE_APPROVAL

{
  "decision": "REQUIRE_APPROVAL",
  "authorizationId": "auth_58201",
  "approvalId": "apr_72f83",
  "reasonCodes": [
    "APPROVAL_THRESHOLD_EXCEEDED"
  ]
}

Agent credentials

256-bit generated keys, hashed at rest, revocable and bound to one agent.

Idempotent requests

The same key and payload returns the same logical authorization result.

Exact approvals

Approval pauses one authorization and is consumed by that request alone.

One-time execution

A unique execution claim prevents the provider adapter from being invoked twice.

Prefer raw HTTP?

The SDK is a thin typed client over the same REST contract. Use curl, another language or your existing agent runtime.

authorize.sh typed contract

curl -X POST http://localhost:4000/v1/authorize \
  -H "Authorization: Bearer $CAPYN_API_KEY" \
  -H "Idempotency-Key: inference-order-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "capability": "spend.compute",
    "amount": { "value": "18.42", "currency": "USD" },
    "vendor": { "id": "openai", "name": "OpenAI" },
    "metadata": { "purpose": "Inference capacity" }
  }'

Start with the decision point

Give the agent a mandate, not the treasury keys.

Run the four-scenario demo locally or inspect the working control plane in the browser.

Open control plane Read developer guide