Ask Writ whether an action may proceed. CALL THIS BEFORE any consequential write.

A consequential write is anything hard to undo: sending money or messages, changing access or identity records, deleting data, calling an external API that acts in the world.

Args: sponsor_id: The human sponsor accountable for this action (e.g. a user id or email). agent_id: The agent or workflow performing the action. verb: What is being done (e.g. "verify_human", "send_payment"). target: What it acts on (e.g. "benefit-case-123"). purpose: Why, in plain words. Be specific — the approval is bound to this purpose. environment: Optional policy environment: "dev", "staging", or "prod". The check runs against that environment's policy override (verbs it doesn't override inherit the tenant default). Omit for the tenant default. An unknown name denies fail-closed — never silently falls back.

Returns a decision: ALLOW — proceed. You get an authToken valid 90 seconds, bound to this exact sponsor/agent/verb/target/purpose. Call writ_verify_token against the intended write immediately before executing it. DENY — do NOT perform the action. Explain the receipt reason to the user. STEP_UP — a human sponsor must approve first. Tell the user what needs approval; they can approve via writ_grant (or the dashboard), then call writ_check again. Every outcome creates an audit receipt with a receiptId.

Verify a Writ auth token against the write you are about to execute.

Call this IMMEDIATELY before executing an ALLOWed write, with the exact verb/target/purpose you intend. If valid is false — expired, tampered, or bound to a different purpose — do NOT execute the write; call writ_check again.

This is the point-of-action enforcement: the check authorizes, the token proves the authorization still matches what you are actually doing.

Convert an ALLOW token into a single-use gated-execution lease.

Call this AFTER writ_check returns ALLOW, passing that ALLOW's authToken. The lease is bound to the exact upstream request you intend to run: the same method, path, and body bytes you will later pass to writ_execute. A lease is single-use; once executed (or expired) it is spent.

Args: auth_token: The authToken from a writ_check ALLOW decision. system_id: The registered upstream system: "stripe", "github", or "salesforce". A vaulted credential must be active for this system or the gate answers ok:false. method: HTTP method of the upstream request (e.g. "POST"). path: Upstream path (e.g. "/v1/refunds"). Must match the system's allowed path patterns. body: Optional JSON object (at most 1 MB). Sent only when provided; if you lease a body you must execute the identical body. ttl_seconds: Optional lease TTL in seconds. The gate caps it at 90 and at the token's remaining life.

On success the gate answers 201 with leaseId, expiresAt, ttlSeconds, verb, target, purpose, and systemId. On failure it answers {"ok": false, "reason": ...} (token invalid or expired, or no active vaulted credential for the system). On ok:false do NOT execute.

Run one gated upstream request with a lease or ALLOW token.

Pass exactly one of lease_id (from writ_lease) or auth_token (from a writ_check ALLOW). Pass the SAME method, path, and body as the lease: the gate compares the request bytes against the lease, and on any mismatch it fails closed: no upstream call is made and the answer is {"ok": false, "reason": ..., "upstreamCalled": false}.

Args: lease_id: The leaseId from writ_lease. Mutually exclusive with auth_token. auth_token: An ALLOW authToken from writ_check. Mutually exclusive with lease_id. system_id: The registered upstream system: "stripe" (default), "github", or "salesforce". method: HTTP method of the upstream request (required, e.g. "POST"). path: Upstream path (required, e.g. "/v1/refunds"). body: Optional JSON object. Must be byte-identical to the leased body. idempotency_key: Optional key passed through to the upstream system. Use it so retries are safe.

On success the gate returns the upstream system's status and body verbatim. Every outcome writes a receipt. On {"ok": false} report the reason to the user and do NOT retry with a different request: the lease is spent or invalid.

SPONSOR ONLY. Mint a one-time grant approving a specific action.

Use this when writ_check returned STEP_UP and the human sponsor approves. The grant is single-use: the next writ_check consumes it and returns ALLOW. The grant is scoped to your tenant. Requires WRIT_SPONSOR_TOKEN.

SPONSOR ONLY. Kill switch: immediately deny all future checks for this principal.

Revocation overrides live grants and tenant policy. Use when a principal is compromised, misbehaving, or its task is done. Scoped to your tenant. Requires WRIT_SPONSOR_TOKEN.

SPONSOR ONLY. Undo writ_revoke: the principal is evaluated by policy again.

Scoped to your tenant. Requires WRIT_SPONSOR_TOKEN.

List recent decision receipts (audit trail). Newest first.

Read the tenant's verb policy: which verbs allow, deny, require a grant, or step up.

Get a free 90-second sandbox grant for a demo write. No API key needed.

Issues a live grant for verb "demo_write" on a target starting with "demo-", then runs writ_check so you get back an ALLOW decision plus auth token to practice the verify-before-write flow end to end.

List the GitHub App installations for this tenant.

Returns each installation's id, status, PR-comment bot setting, and the per-installation check-run fail threshold (checkFailUngated). Use this to discover installation ids before calling writ_github_set_threshold or writ_github_toggle_pr_comments.

Set the per-installation check-run fail threshold.

A positive number N makes the GitHub check run fail when the ungated-site count is greater than N; a zero-ungated scan passes. Omit threshold (or set it to None) to clear the override and restore neutral-only check runs.

Enable or disable the optional PR-comment bot for a GitHub App installation.

Default is OFF. No TOTP step-up is required. Use writ_github_installations to find installation_id.

List scanned repos and their risk profiles, or fetch one manifest.

With no repo_id, returns a table of repos with writScore, scanStatus, and riskDigest (counts per risk class). With repo_id, returns the full signed manifest for that repo.

Fetch a receipt and explain it in plain language.

Use this to understand why a writ_check returned ALLOW, DENY, STEP_UP, or REVOKED. Returns the receipt with a human-readable breakdown.

Get or update step-up notification settings.

With no arguments, returns the current settings. With arguments, updates them: step_up_email enables/disables step-up emails; step_up_webhook_url sets a generic or Slack webhook URL; use an empty string to clear.

List the tenant's principals (identity directory).

List the tenant's verb vocabulary, including custom verbs.

List API key metadata for the tenant (never raw keys).