@auctra/sdk

Official TypeScript SDK for Auctra — Authority Protocol for autonomous actors.

| Resource | URL | | -------------------------- | ------------------------------------------------------------- | | Console | https://app.auctra.tech | | Sign up (free Developer) | https://app.auctra.tech/auth/signup | | Docs | https://auctra.tech/docs | | OpenAPI 3.1 | https://app.auctra.tech/v1/openapi.json | | API base URL | https://app.auctra.tech (DEFAULT_BASE_URL — override with baseUrl) |

Install

npm install @auctra/sdk

Canonical API (v0.6+)

auctra.authority.issue()
auctra.authority.verify()
auctra.authority.delegate()
auctra.authority.revoke()

auctra.action.evaluate()   # dry-run Decision
auctra.action.execute()    # enforce + Evidence (pass `intent` from createIntent on every action)
auctra.getActionRequest()  # dispute pack (decision, receipt, evidence)

auctra.listIncidents() / openIncident() / resolveIncident()   # Startup+
auctra.listCompliancePacks() / runCompliancePack() / listComplianceRuns()  # Startup+
auctra.listSiemEndpoints() / createSiemEndpoint() / deleteSiemEndpoint()  # Startup+
auctra.exportAuditEvents()  # Startup+ SIEM pull (siemExport)
auctra.listPolicyTemplates() / applyPolicyTemplate()  # Pro+
auctra.approveActionRequest() / rejectActionRequest() / escalateActionRequest()  # admin API key

auctra.evidence.verify()

API keys are created in the console only (listApiKeys is available in the SDK). Approvals via SDK require an admin key (not write-only).

There is no public createDelegation() or evaluateAction().

Quick start

import { Auctra } from "@auctra/sdk";

const auctra = new Auctra({
  apiKey: process.env.AUCTRA_API_KEY!,
  // baseUrl defaults to https://app.auctra.tech — set for staging/local only
  timeoutMs: 10_000,
  maxRetries: 2,
});

const agentId = "your-agent-uuid";
const expiresAt = new Date(Date.now() + 30 * 864e5).toISOString();

const { authority } = await auctra.authority.issue({
  subject: agentId,
  capabilities: ["send_payment"],
  constraints: { maxAmount: 1200, currency: "USD" },
  expiresAt,
});

// Declare human intent first — every action.execute needs the returned anchor_token
const { intent } = await auctra.createIntent({
  title: "Pay matched vendor invoices",
  intentType: "payment",
  riskLevel: "high",
  maxRiskLevel: "critical",
  allowedActionTypes: ["send_payment"],
  expiresAt,
});

// Dry-run
await auctra.action.evaluate({
  agentId,
  actionType: "send_payment",
  payload: { amount: 500, currency: "USD" },
  intent, // wires claimed_intent_id + intent_anchor_token
});

// Production enforcement path
const decision = await auctra.action.execute(
  {
    agentId,
    actionType: "send_payment",
    payload: { amount: 500, currency: "USD", target: "vendor:acme" },
    intent, // do not pass claimedIntentId alone — omit anchor → require_approval
    action: {
      target: "vendor:acme",
      description: "Net-30 invoice payment",
      riskLevel: "medium",
    },
  },
  { idempotencyKey: crypto.randomUUID() },
);

if (decision.decision === "allowed") {
  // proceed
} else if (decision.decision === "require_approval") {
  console.log(decision.reason, decision.action_request_id);
} else {
  // "blocked" includes over-maxAmount, unknown agent, revoked/expired grant
  throw new Error(decision.reason);
}

const pack = await auctra.getActionRequest(decision.action_request_id);

Delegate (Child ⊆ Parent)

const child = await auctra.authority.delegate({
  parent: authority.id,
  subject: "logistics-agent-uuid",
  capabilities: ["send_payment"],
  constraints: {
    maxAmount: 300,
    currency: "USD",
    maxLifetimeActions: 50,
    maxLifetimeAmount: 10_000,
  },
  expiresAt,
});

Scope escalation is rejected by the protocol/runtime.

Intent anchors (read this first)

createIntent returns { intent: { id, anchor_token, ... } }. Pass the whole intent object into every action.evaluate / action.execute:

const { intent } = await auctra.createIntent({ /* ... */ });
await auctra.action.execute({ agentId, actionType, payload, intent, action: { /* ... */ } });

Do not send claimedIntentId without intentAnchorToken — the runtime returns require_approval with a message about the missing anchor. That is intentional (fail-safe), not a policy misconfiguration.

Full onboarding guide: docs/integrations/intent-anchors.md.

List authorities efficiently — filter by agent to avoid loading full org history:

const { delegations } = await auctra.listAuthorities({
  agentId,
  status: "active",
  limit: 100,
});

Revoke stale grants before issuing new ones on the same agent (prevents composition blocks). See docs/integrations/authority-gate-guards.md.

Threat-engine helpers (≥ 0.6.11)

Lifetime budgets (Engine 12) — cap total actions or spend across the delegation lifetime:

await auctra.authority.issue({
  subject: agentId,
  capabilities: ["send_payment"],
  expiresAt,
  constraints: {
    maxAmount: 1200,
    currency: "USD",
    maxLifetimeActions: 100,
    maxLifetimeAmount: 25_000,
  },
});

Untrusted tool/MCP outputs (Engine 03) — declare provenance on medium+ and any RAG/document/tool-sourced action so untrusted content cannot authorize the next step. Omitting action.metadata.inputs on those paths now fail-closes (PROVENANCE_REQUIRED / TOOL_PROVENANCE_REQUIRED). Use @auctra/mcp-gateway declareToolResponseInput or pass action.metadata.inputs directly:

await auctra.action.execute({
  agentId,
  actionType: "send_payment",
  payload: { amount: 500, currency: "USD" },
  intent,
  action: {
    target: "vendor:acme",
    metadata: {
      inputs: [
        {
          source: "mcp:fetch_invoice",
          source_type: "mcp_tool_response",
          trust_level: "untrusted",
          authority: "none",
          content_hash: "sha256:…",
        },
      ],
    },
  },
});

See docs/UNTRUSTED_INPUT_INTEGRITY.md and docs/security/threat-coverage-architecture.md.

Composition block (Engine 10) — create a composition_block policy with forbiddenPairs so concurrent grants cannot combine read/export with outbound write:

await auctra.createPolicy({
  name: "Block read + email",
  policyType: "composition_block",
  status: "draft",
  decision: "block",
  forbiddenPairs: [
    ["export_data", "send_email"],
    ["read_pii", "send_email"],
  ],
});

Or apply the console template (Policies → Start from a template) as a draft, simulate, then publish.

Delayed side effects (Engine 11) — use onAllowed / assertAuthorityLive, or pass executeAfter so Auctra re-validates before release. See docs/integrations/execution-contract.md.

Fail-closed guards (400 / 404)

Unregistered action types return HTTP 400; unknown agent_id returns HTTP 404. Both map to { decision: "blocked", guard: { httpStatus } } in the SDK (≥ 0.6.5) — that is not a bug and not an invitation to auto-register shadow tools. See docs/integrations/authority-gate-guards.md.

Docs

See https://app.auctra.tech/docs, docs/integrations/intent-anchors.md, docs/integrations/authority-gate-guards.md, docs/security/authority-gate.md, and docs/AUTHORITY_PROTOCOL_ARCHITECTURE.md.