INTYGA Developer Reference

Connect your agent

In the console, open My Agents → create an agent (this mints its DID and links you as its owner) → mint its agent API key. Exchange it for a token, then point a Streamable HTTP MCP client at the gateway:

TOKEN=$(curl -s -u "$CLIENT_ID:$CLIENT_SECRET" -X POST https://api.intyga.com/oauth/token | jq -r .access_token)

# Manual test in Codex; the client must inherit this environment variable:
export INTYGA_MCP_TOKEN="$TOKEN"
codex mcp add intyga --url https://api.intyga.com/mcp \
  --bearer-token-env-var INTYGA_MCP_TOKEN

Or in an mcp.json-style client configuration:

{
  "mcpServers": {
    "intyga": {
      "type": "streamable-http",
      "url": "https://api.intyga.com/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

The exchanged token expires after 15 minutes. A persistent client must refresh it; a static token in either example is for a short manual test. See the public agent setup instructions for the complete v1 connection and receipt requirements. The executing service must prepare and retain agentContext from its own state before an AI-agent request.

Usage pattern: the agent calls verify_human_authorization (keeps the nonce), then polls check_human_authorization every ~2s until the status leaves PENDING, and finally verifies the returned receipt before executing the tool. Challenges expire after 120s by default, so an ignored request fails safe. You approve with your passkey on the console Challenges page.

Creates a signing challenge bound to the action and notifies the human owner to approve it with their registered passkey. Returns immediately with the challenge nonce and a PENDING status.

Arguments Schema:

{
  "action": "string, required (e.g. 'wire_transfer')",
  "target": "string, required — the execution environment that will perform it
             (e.g. 'prod-db-cluster-01'). Bound into the signature so an approval
             cannot be replayed against a different target (DIV Target Isolation).",
  "actionDescription": "string, required (e.g. 'Wire $50,000 to ACME Corp')",
  "params": "object, required (e.g. {\"to\": \"ACME-123\", \"amount\": 50000})
             — displayed key-by-key to the human AND bound to their signature.
             This is what prevents blind-signing.",
  "amount": "number (optional, also folded into params)",
  "currency": "string (optional, 3-letter ISO)",
  "agentContext": {
    "action": { "reversibility": "irreversible", "amount": null },
    "configDigest": "sha256:<64 lowercase hex from live model, tools and prompt>",
    "delegatedBy": null,
    "session": {
      "id": "sha256:<64 lowercase hex from random opaque session ID>",
      "seq": "1", "prev": null, "aggregate": null
    }
  }
}

Note that action here is the wire name for what the SDK calls actionType — same field, and it is the string your server-side Approval Rules match on. agentContext is required for an AI_AGENT key. The values shown above are placeholders, not valid digests: your executing service must compute them from its own runtime and durable session state. Monetary actions use decimal strings for both action.amount and session.aggregate. Keep raw prompts and personal data out of these new receipt fields.

Response Schema:

{
  "nonce": "string (UUID challenge token)",
  "status": "PENDING" | "APPROVED",
  "agentContext": "issuer-completed v1 context for AI_AGENT | undefined"
}

Authoring Policies (Zero-Knowledge)

Policies are JSON manifests of governance rules. They are validated and encrypted with your organization's public key — in your browser (Ops Console) or off-platform with the @intyga/sdk CLI — then published as an opaque ciphertext + SHA-256 hash. INTYGA never sees the plaintext and never holds your private key (true zero-knowledge).

The gateway enforces only version freshness: an agent presents its policy hash (X-INTYGA-Policy-Hash) on connect; a stale hash is rejected with 409 policy-update-required, prompting a re-fetch from GET /policy/current. Your agent runtime (holding the org private key) decrypts and enforces the rules locally — the gateway stays an opaque relay.

Publish off-platform (hard zero-knowledge):

# Generate keys on YOUR machine — INTYGA only ever receives the public key
intyga keygen --out org                 # → org.public.key (upload) + org.private.key (KEEP SAFE)

# Validate + encrypt the manifest locally, publish only ciphertext + hash
intyga policy-encrypt policy.json --pubkey org.public.key --out blob.json

Policy Rule Schema:

• action (string, required): The target tool name matching the agent tool call, e.g., execute_sql, send_email.
• effect (string, optional): The outcome of the match. One of:
  • deny: Blocks tool execution immediately, returning a Security Violation error. This is the only effect the gateway acts on — it can only ever make governance stricter.
  • require_approval (default): Halts execution and triggers a signed passkey approval challenge.
  • allow: Records a local policy decision. The shipped MCP wrapper and proxy still request gateway authorization and verify the required receipt before executing the tool. A local rule cannot bypass server-side Approval Rules.
• maxAmount (number, optional): If the tool call parameters include an amount field, exceeding this limit downgrades an allow to require_approval during local evaluation. Both outcomes still go through the gateway in the shipped adapters. Enforce real spend limits with a server-side Approval Rule; the gateway does not trust a client allow.
• currency (string, optional): A 3-letter ISO currency string (e.g. USD) companion for the amount limits.

Example Manifest:

{
  "version": "2026.07.05-1",
  "rules": [
    {
      "action": "delete_database",
      "effect": "deny"
    },
    {
      "action": "wire_transfer",
      "effect": "allow",
      "maxAmount": 5000,
      "currency": "USD"
    },
    {
      "action": "reboot_server",
      "effect": "require_approval"
    }
  ]
}

@intyga/sdk (Library)

One SDK for authorization and offline verification. The example below uses a human or SERVICE (pipeline) key. An AI_AGENT key additionally requires the v1 agentContext on the request and verifyAgentForExecution at the execution boundary; see the MCP section above. Verification is re-exported from the standalone @intyga/verify package: recompute the canonical payload from YOUR params, confirm it byte-matches what was signed, and check the human's signature — offline, no INTYGA secret.

For a tool server, @intyga/mcp-sdk accepts an agentV1 runtime. For a third-party stdio server, launch @intyga/mcp-proxy --agent-v1-module ./rp-agent-v1.mjs. Both send the v1 agent context, verify the receipt, and require your RP's atomic nonce/session/budget reservation before execution. Supply live model, tool and prompt data plus trusted approver keys from your own environment; the agent cannot attest these for itself. See each package README for the runtime interface.

import { IntygaClient, verifyApprovalReceipt } from "@intyga/sdk";

const intyga = new IntygaClient({
  gatewayUrl: "https://api.intyga.com",
  clientId: process.env.INTYGA_CLIENT_ID,     // human or SERVICE key in this example
  clientSecret: process.env.INTYGA_CLIENT_SECRET,
});

const action = {
  target: "prod-db-cluster-01",              // WHERE it runs — bound into the signature
  actionType: "wipe_production",
  params: { db: "prod-1" },
};

// Blocks until the human approves with their passkey / security key (or times out):
const r = await intyga.requireApproval("Delete production database", action);
if (r.status !== "APPROVED") throw new Error("not authorized");

// Prove — offline, no network, no INTYGA secret — that a human signed THIS exact instruction.
// nonce and approvers come from YOUR side: a receipt cannot vouch for its own signer.
const check = verifyApprovalReceipt(r.receipt!, {
  ...action,
  nonce: r.nonce!,
  approvers: { publicKeys: TRUSTED_APPROVER_KEYS },
}, {
  expectedOrigin: anchor.webauthn?.origin,
  expectedRpId: anchor.webauthn?.rpId,
});
if (!check.ok) throw new Error(`receipt failed to verify: ${check.reason}`);
// ...safe to proceed.

Matching

The * rule is the tenant baseline. Another rule matches only when its action ID exactly equals actionType; display text never selects it. The specific rule must preserve every baseline requirement, or the request is refused. Rules live per tenant and are configured in the console (each change is itself a step-up signed mutation, so the governance config has the same audit trail as the actions it governs).

When no exact rule matches, new workspaces deny the request. Administrators may explicitly choose baseline approval for unknown action IDs. If the baseline requires hardware, a specific rule also has to require hardware, whatever its quorum. Migrated workspaces retain recorded legacy behavior until an administrator activates exact matching. Preview the effective requirements on Approval Rules before activation. Offline consumers need a fresh v1 trust bundle and a compatible SDK.

Constraints

• requiredApprovals (default 2): distinct valid signatures needed before the challenge flips to APPROVED. M-of-N multi-signature.
• approverDids / approverGroupIds: who is eligible. Groups are expanded into a snapshot when the challenge is created — editing a group never affects an in-flight challenge (fail-closed).
• requesterCannotApprove: four-eyes. The approver must be a different identity than the requester, so nobody ratifies their own request.
• requireHardwareKey / allowedAaguids: the approving credential must be a device-bound (non-synced) authenticator, optionally narrowed by AAGUID to a specific model — e.g. a corporate YubiKey fleet. Synced passkeys are rejected.
• requireAttestedRequester / allowedIssuers: the machine-side mirror. The requesting workload must have proved its identity by third-party attestation (OIDC / SPIFFE). A plain client-credentials agent never satisfies it, and neither does DPoP — key possession is self-asserted, not provenance.
• escalateAfterSeconds + escalationApproverDids / escalationGroupIds: a still-pending challenge adds approvers and re-notifies. Escalation only ever widens who may sign — it never lowers the quorum, bypasses four-eyes, or extends expiry.
• autoApproveWindow*: pre-approval windows (start, end, day of week, and the specific requester DID it applies to). Actions approved this way produce a receipt with sigAlg: "AUTO_APPROVED" and no human signature — which is exactly why verifyApprovalReceipt refuses those by default. This is a policy convenience, not a break-glass mechanism: for approving actions while INTYGA is unreachable, see Offline Approval.

1. Offline — no network, no account (recommended)

verifyApprovalReceipt from @intyga/verify re-derives the canonical payload from your parameters and checks the signature locally. This is the guarantee: it keeps working if INTYGA is down, and it keeps working if INTYGA no longer exists.

2. Ledger inclusion — against an independently trusted root

A receipt proves an approval happened. An inclusion proof checks that an event was committed under a particular root; by itself it does not prove the whole log is complete. Export the proof from Audit and compare it against a root obtained through your independently trusted checkpoint channel. The file below is your retained root list, not a public repository assumed to exist. Gapless tenant-sequence checks concern committed events only; they cannot expose an event withheld before commitment.

npx @intyga/sdk audit-verify ./intyga-audit-proof-seq-1234.json \
  --roots roots/roots.jsonl
# exit 0 = verified, 1 = not verified