API Reference

Redirect to OIDC provider. Returns 302 to the configured identity provider login page.

OIDC callback. Validates code + state, sets session cookie, redirects to /policies.

Emails a one-time sign-in link. Body: {"email": "..."}. Always returns 200, whether or not the address is known; rate limited.

Exchanges the link's ?token= for a 24-hour session. An invalid or expired token returns 401.

Single sign-on. Takes ?email=, finds the organization that verified that email's domain, and redirects to its identity provider.

Clears the session cookie. Returns {"status":"logged_out"}.

Returns the identity of the authenticated caller.

// API key response
{
  "authenticated": true,
  "auth_method": "api_key",
  "tenant_id": "acme-corp"
}

// OIDC session response
{
  "authenticated": true,
  "auth_method": "oidc",
  "tenant_id": "acme-corp",
  "user": {
    "id": "usr_abc",
    "email": "alice@acme.com",
    "name": "Alice",
    "avatar_url": "https://..."
  },
  "roles": ["admin"]
}

List all policies. Query params: status (draft|pending_approval|deployed|revoked), agent_role, limit, offset.

{
  "policies": [
    {
      "id": "pol_abc123",
      "dsl_source": "policy \"my_policy\" { ... }",
      "status": "deployed",
      "version": 3,
      "content_hash": "sha256:...",
      "author_id": "usr_abc",
      "created_at": "2025-07-01T10:00:00Z",
      "updated_at": "2025-07-24T09:15:00Z"
    }
  ]
}

Create a new policy. The policy starts in draft status and must be approved before deploying.

{
  "id": "my_policy",
  "dsl_source": "policy \"my_policy\" {\n  agent_role = \"analyst\"\n  ...\n}"
}

{
  "id": "my_policy",
  "status": "draft",
  "version": 1,
  "content_hash": "sha256:...",
  "created_at": "2025-07-24T10:00:00Z"
}

Get a single policy with full DSL source and version history.

Update a policy's DSL source. Creates a new version.

{ "dsl_source": "policy \"my_policy\" { ... }" }

Revoke a policy. The proxy stops enforcing it within one poll interval.

Roll back to a previous version.

{ "target_version": 2 }

Validate DSL syntax without saving. Returns structured errors with line and column positions.

{ "dsl_source": "policy \"test\" { ... }" }

{
  "valid": false,
  "errors": [
    { "line": 4, "column": 3, "message": "unexpected token 'denye'" }
  ],
  "warnings": []
}

Fetch the compiled binary policy bundle. Used by the proxy. Returns 304 Not Modified if bundle hash matches current_hash query param. Pass ?scopes=default,finance to receive only policies tagged with those scopes — the control plane filters and re-signs the bundle before returning it.

List all API keys. The plaintext key value is never returned after creation.

{
  "keys": [
    {
      "id": "key_abc",
      "label": "production-proxy",
      "prefix": "clk_free.xxxx",
      "created_at": "2025-07-01T10:00:00Z"
    }
  ]
}

Issue a new API key with the scopes it needs: proxy (for clausgap-proxy), pipeline (policies as code) or admin. A key may make only the requests its scopes allow. The plaintext key is returned once.

{ "label": "production-proxy", "scopes": ["proxy"] }

{
  "id": "key_abc",
  "key": "clk_free.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "label": "production-proxy",
  "scopes": ["proxy"],
  "created_at": "2025-07-24T10:00:00Z"
}

Revoke an API key. Takes effect immediately — the proxy will fail to fetch bundles on the next poll.

List escrow holds. Query params: status (held|released|rejected|consumed|expired|cancelled), agent_role, agent_id, action_type, min_value, max_value, limit, offset.

Get a single escrow hold. Poll this endpoint to check if the hold has been released.

{
  "id": "esw_abc123",
  "agent_role": "treasury_bot",
  "agent_id": "bot-1",
  "action_type": "api_call",
  "action_summary": "POST /submit_payment",
  "status": "held",
  "hold_type": "multi_party",
  "required_approvals": 2,
  "current_approvals": 1,
  "estimated_value": 48200.00,
  "value_currency": "USD",
  "risk_score": 0.85,
  "ttl_seconds": 3600,
  "expires_at": "2025-07-24T15:30:00Z",
  "created_at": "2025-07-24T14:30:00Z"
}

Cast an approval or rejection vote (one per person). When required_approvals is reached the hold is released; any rejection rejects it.

{
  "decision": "approve",
  "reason": "Confirmed with procurement team"
}

{
  "escrow_id": "esw_abc123",
  "your_decision": "approve",
  "current_approvals": 2,
  "required_approvals": 2,
  "status": "released",
  "released_at": "2025-07-24T14:55:00Z"
}

Used by the proxy when the agent resends the approved request. A released hold is consumed exactly once, atomically, and only by the agent that requested it for the exact action approved. Refusals: 409 ALREADY_CONSUMED, 422 HASH_MISMATCH (a different request), 403 AGENT_MISMATCH (another agent), ESCROW_EXPIRED, INVALID_STATUS.

{ "action_hash": "sha256:…", "agent_role": "treasury_bot", "agent_id": "bot-1" }

Mark an external condition as satisfied (for conditional hold type).

{ "condition_id": "ci_check", "satisfied": true, "evidence": "build:12345" }

Cancel an escrow hold.

{ "reason": "Action no longer needed" }

List decision events. Query params: event_type, agent_id, session_id, decision (allow|allow_with_masking|deny|escrow|rate_limited), since (ISO 8601), after (cursor), limit (1–1000).

{
  "events": [
    {
      "id": "evt_abc",
      "event_type": "decision.deny",
      "proxy_id": "proxy-1",
      "agent_role": "analyst",
      "agent_id": "a-123",
      "session_id": "sess-xyz",
      "tool_name": "delete_records",
      "method": "DELETE",
      "decision": "deny",
      "policy_id": "my_policy",
      "deny_reason": "explicit deny rule matched",
      "evaluation_us": 312,
      "created_at": "2025-07-24T14:30:00Z"
    }
  ],
  "next_cursor": "evt_xyz",
  "has_more": true
}

Get a single event with full detail including input hash, policy snapshot reference, and forensic chain position.

Batch-ingest events from the proxy. Max 100 events per request. Used internally by the proxy.

{
  "events": [
    {
      "event_id": "evt_abc",
      "event_type": "decision.allow",
      "timestamp": "2025-07-24T14:30:00.000Z",
      "tenant_id": "acme-corp",
      "proxy_id": "proxy-1",
      "agent_role": "analyst",
      "agent_id": "a-123",
      "session_id": "sess-xyz",
      "tool_name": "web_search",
      "method": "GET",
      "decision": "allow",
      "policy_id": "my_policy",
      "confidence": 0.95,
      "evaluation_us": 312,
      "total_latency_ms": 45
    }
  ]
}

Recompute the tenant's whole forensic chain. verified: false means a record was altered, inserted or removed; first_mismatch_id is where tampering starts. GET /v1/audit/verify does the same for the administrative audit log.

{ "verified": true, "linear": true, "records_checked": 1520 }

Export every record in a time window (default: the last month), or one session (sequence_id), as a signed evidence package — up to 10,000 records. The package is stored exactly as signed; record package_hash to prove later which package you were given.

{ "purpose": "regulatory_inquiry", "from": "2026-09-01T00:00:00Z", "to": "2026-10-01T00:00:00Z" }

{
  "package_id": "epkg_…",
  "record_count": 1520,
  "chain_intact": true,
  "package_hash": "sha256:2365cc1e…",
  "public_key_fingerprint": "sha256:c3385619…"
}

Download the package — the same bytes every time, after restarts and later database changes. Verify it offline: clausgap-verify --pubkey clausgap.pub package.json (the public key is served at /pubkey).

List exported packages, with each package_hash.

List all webhook subscriptions.

Create a subscription. destination_type is webhook (default), slack, or teams — see the note above. Leave event_types empty for every event. Private, loopback and cloud-metadata destinations are refused when saved.

{
  "url": "https://your-server.com/clausgap-webhook",
  "secret": "whsec_...",
  "event_types": [
    "escrow.created",
    "escrow.released",
    "escrow.vote_cast",
    "policy.approved"
  ],
  "active": true
}

// Or, for a native Slack/Teams destination — no secret needed:
{
  "destination_type": "slack",
  "url": "https://hooks.slack.com/services/T000/B000/XXXXXXXX",
  "event_types": ["escrow.created", "escrow.released"],
  "destination_config": { "app_url": "https://app.clausgap.dev" }
}

{
  "id": "sub_abc",
  "url": "https://your-server.com/clausgap-webhook",
  "destination_type": "webhook",
  "event_types": ["escrow.created", "escrow.released"],
  "active": true,
  "created_at": "2025-07-24T10:00:00Z"
}

Update a subscription (url, secret, event_types, active).

Delete a subscription. Deliveries already queued for it are not sent.

Send a signed test event (clausgap.test) to the destination now and report the result: DELIVERED, DESTINATION_BLOCKED, TIMEOUT, DNS_ERROR, TLS_ERROR, CONNECTION_FAILED, REJECTED_BY_DESTINATION, NOT_FOUND or DESTINATION_ERROR, with a reason. Webhook results include the payload sent.

{
  "delivered": false,
  "result": "REJECTED_BY_DESTINATION",
  "reason": "the destination refused it (HTTP 401) — if it verifies X-Clausgap-Signature, check it uses this subscription's signing secret",
  "http_status": 401,
  "duration_ms": 41
}

List recent deliveries for a subscription: status (delivered, retrying, failed), attempt count, HTTP status, the reason for the last failure in plain words, and when a retrying delivery is next attempted. Failed deliveries are retried with backoff for 24 hours; a refused destination fails at once.

List all team members.

{
  "users": [
    {
      "id": "usr_abc",
      "email": "alice@acme.com",
      "name": "Alice",
      "avatar_url": "https://...",
      "roles": ["admin"],
      "created_at": "2025-06-01T00:00:00Z",
      "last_login": "2025-07-24T08:00:00Z"
    }
  ]
}

Grant a role (viewer, author, approver or admin). Granting a role the user already holds is a 409; a role revoked earlier is granted again.

{ "role": "approver" }

Revoke a role from a user.

Invite someone by email with a role. They join by the emailed link, or — with SSO set up — simply by signing in through your identity provider.

{ "email": "rae@acme.com", "role": "approver" }

Remove a member: their roles go and their sessions end at once, and they can't sign in again — by SSO or emailed link — until invited again (which restores the same account).

Configure the identity provider. The issuer is checked straight away (OIDC discovery).

{ "issuer_url": "https://login.acme.com/", "client_id": "clausgap", "client_secret": "…" }

Claim an email domain. The response's domain_records give the TXT record to publish; another organisation having verified the domain is a 409.

{ "domain": "acme.com" }

{
  "domain_records": [{
    "domain": "acme.com",
    "verified": false,
    "txt_name": "_clausgap-verification.acme.com",
    "txt_value": "clausgap-domain-verification=2d076bea…"
  }]
}

Check DNS for the TXT record and, if it's there, start routing the domain's sign-ins to your identity provider. 422 DOMAIN_NOT_VERIFIED says which record was missing.