Skip to content

Human approvals

Human approvals and questions are the decision layer of agent state. When agents take side-effect actions (such as issuing refunds, sending emails, deleting datasets, or filing tickets) or need human input to proceed, the Approvals API routes requests to specific people and records their answers in an append-only audit log under the same enterprise boundary and access model as agent memory and application data.

POST /v1/approvals
{
  "request_key": "refund-order-1234",
  "title": "Refund order 1234",
  "summary": "Customer asked for a full refund of $42.00.",
  "payload": { "order_id": "1234", "amount_cents": 4200 },
  "approvers": [{ "email": "dana@acme.example" }],
  "quorum": "QUORUM_ANY_ONE",
  "ttl_seconds": 86400
}

In addition to binary approve/reject requests, agents can send structured questions with predefined choices or free-text input and read the response from the resolved approval record.

When an approval request is created, Jennah sends notification emails containing secure decision links to designated approvers. Each email begins with the enterprise name and identifies the requester: either the API key (by label and last 4 characters) or the enterprise member (by email address). For example:

Acme asks you to approve a request from its API key refunds agent (ending a1b2).

If the requester cannot be resolved, the email lists only the enterprise name. The request payload is formatted as indented JSON without escaping characters such as <, >, and &.

On the approval record, created_by_key_id stores the API key ID when created with an API key, and created_by_user_id stores the member's user ID when created with a user session. (For approvals created before the November 2026 release, created_by_key_id recorded the user ID of the member who created the API key.)

Applications can await decisions using the wait endpoint:

POST /v1/approvals/{approval_id}:wait
{ "timeout_seconds": 30 }

Enforcement model

Jennah records whether a human was asked and what they decided. It does not intercept tool calls or automatically enforce decisions. Your application code must check the approval status (e.g., via :wait) before executing actions.

Automatic gating of tool calls belongs in an execution engine that can pause steps. The Approvals API handles the decision requests and resolutions.

Application pattern (the credential needs approval.requests:create to raise the request and approval.requests:read to wait on it):

approval = jennah.approvals.create(
    request_key=f"refund-{order_id}", ...
)

# The SDK loops the bounded server-side wait for you.
outcome = jennah.approvals.wait(approval.approval_id)
if outcome.status != "APPROVAL_STATUS_APPROVED":
    return "refund not authorized"

# Execute the action only after verifying approval status.
issue_refund(order_id)

Agents connected over MCP can create approval requests with the request_approval tool, and read requests and their decisions with list_approvals and get_approval. In MCP configurations, approvers and quorum rules are fixed at the server level and cannot be chosen or modified by the model.

Creating a request

Idempotency with request_key

Creation requests require a request_key unique to the enterprise and agent. Replaying the same key with identical content returns the original approval without resending notifications; the response sets already_existed: true.

Reusing a key with modified request parameters (title, summary, payload, approvers, quorum, ttl, etc.) returns an ALREADY_EXISTS error.

Duration over absolute timestamps

Requests specify ttl_seconds rather than absolute expiration timestamps so retried requests compute identical parameters and maintain idempotency.

Delivery vs. storage

A successful create (200 OK) indicates the request is durably stored. Notification delivery occurs asynchronously. Approver delivery details (delivery_state and last_delivery_error) can be queried via:

GET /v1/approvals/{approval_id}

This distinguishes pending responses from delivery failures.

Quorum

QUORUM_ANY_ONE resolves on the first approval. QUORUM_ALL requires every listed approver to approve. A single rejection is immediately terminal under either quorum, regardless of prior approvals.

Reads report required_approvals and approvals_recorded to show partial approval progress.

Other request fields

Field Meaning
agent_id Optional agent the request is about. The caller must have reach over that agent, or the create is PERMISSION_DENIED.
required_approvals Optional. When set it must equal the value the quorum implies (1 for QUORUM_ANY_ONE, the approver count for QUORUM_ALL); a mismatch is INVALID_ARGUMENT. Leave it unset and the server derives it.
record_to_memory When agent_id is set, writes the final outcome into that agent's memory as an execution-log step. Ignored without agent_id. A failed memory write never changes the decision.
notify_run_id, notify_signal_name Reserved. Stored and returned unchanged on reads.

Formatting the summary

The summary field accepts Markdown for both approvals and questions (no separate format field is required). The raw Markdown source is stored and returned unchanged by the API, and each surface decides how to present it:

  • The console (the decision page, the approvals inbox, and an agent's approvals list) renders it as Markdown. Long summaries are collapsed behind a "Show all" control so question choices remain visible near the top of the page.
  • Email displays the raw source text with line breaks preserved.

Plain text works without modification: single line breaks render as line breaks, preserving multi-line formatting as written.

For example, a request titled Refund order 1234 could carry this summary (in the JSON request body it is a single string, with each newline written as \n):

## Why

The item arrived **damaged**.
The customer sent photos and asked twice.

- Order: `1234`
- Amount: $42.00
- Ticket: [SUP-981](https://support.example/t/981)

| Check | Result |
| --- | --- |
| Within refund window | yes |
| Prior refunds | 0 |

The console renders this subset of CommonMark, plus GitHub-style tables and strikethrough:

Syntax Example
Paragraphs and line breaks blank line between paragraphs; a single line break is kept
Headings # Heading to ###### Heading (shown smaller than the request title)
Emphasis, strong, strikethrough *em* or _em_, **strong**, ~~struck~~
Inline code `code`
Code blocks fenced with ``` or ~~~ (the info string is shown as a label), or indented 4 spaces
Lists -, +, or * bullets; 1. or 1) numbered; nested
Block quotes > quoted
Thematic breaks ---, ***, or ___
Tables a header row, a delimiter row of --- cells (with : for alignment), then rows, cells separated by pipes
Links [text](https://example.com)

Console rendering enforces the following security rules:

  • Raw HTML is shown as text. Tags, <script>, and HTML comments appear literally as written and are never interpreted.
  • Images are shown as links. ![chart](https://example.com/c.png) renders as a link labeled "image: chart". The console never fetches external images from a summary, preventing tracking pixels from revealing when or from where a request was viewed.
  • Restricted link schemes. Only http, https, and mailto URLs are rendered as clickable links. Any other destination, including javascript:, data:, and relative URLs, is rendered as plain source text. Each link displays its destination host (or mailto address) alongside the link text and opens in a new tab with no referrer.
  • No hidden content. Unsupported syntax, such as reference-style links, footnotes, and link titles, is displayed literally as written. If a summary cannot be parsed, the console falls back to displaying the raw source.

The rendered digest is computed over the raw summary source. Because rendering hides no text, the source is an accurate record of what was shown to the approver.

Expiration behavior

Requests that reach their deadline without a decision resolve to REJECTED or EXPIRED, according to on_expire: ON_EXPIRE_DENY (the default) resolves to REJECTED, and ON_EXPIRE_EXPIRE resolves to EXPIRED. Unanswered requests never default to approved.

Expiration is enforced at the deadline on read and write paths, independent of background sweeps. Reads after the deadline return the terminal status, and late decision submissions are rejected.

Questions

A question prompts an approver to select from predefined choices, provide a free-text response, or both. Questions use APPROVAL_KIND_QUESTION and share the same decision links, idempotency, delivery tracking, waiting, cancellation, and audit behavior as standard approvals.

POST /v1/approvals
{
  "request_key": "rollout-plan-42",
  "kind": "APPROVAL_KIND_QUESTION",
  "title": "Which rollout plan?",
  "question": {
    "choices": [
      { "id": "canary", "label": "Canary first",
        "description": "5% of traffic for an hour" },
      { "id": "all", "label": "All at once" }
    ],
    "allow_free_text": true
  },
  "approvers": [{ "email": "dana@acme.example" }]
}
  • choices are displayed in the order provided. Each choice specifies an id returned in the answer, a display label, and an optional description.
  • multi_select allows selecting multiple choices (requires non-empty choices). When false or omitted, at most one choice may be selected.
  • allow_free_text allows the respondent to submit free-text input, either alongside choices or on its own.
  • A question must specify choices, allow_free_text, or both.

How a question resolves

The first submitted answer resolves the question to APPROVAL_STATUS_ANSWERED and invalidates any remaining decision links for that request. Questions only support QUORUM_FIRST_ANSWER and ON_EXPIRE_EXPIRE (used by default when omitted; other values return INVALID_ARGUMENT).

If an approver declines to answer, the question resolves to APPROVAL_STATUS_REJECTED without an answer payload.

If no response is submitted before the deadline, the question resolves to APPROVAL_STATUS_EXPIRED.

Submitted answers are validated against the question schema (valid choice IDs, single vs. multiple selection, allowed free text, and non-empty response). Invalid submissions return INVALID_ARGUMENT without consuming the decision link.

Reading the answer

When a question resolves to APPROVAL_STATUS_ANSWERED, the approval record includes an answer object:

Field Meaning
choice_ids Selected choice IDs, in selection order
choice_labels Corresponding choice labels
text Free-text response, if provided
approver_id, answered_at Respondent identifier and submission timestamp

Both :wait and GET /v1/approvals/{approval_id} return the answer field once the question is answered. Questions in any other status omit answer. When record_to_memory is enabled, the recorded execution-log step includes the selected labels and free-text response.

Treat the text as untrusted input

Free-text responses contain external user input. Validate or sanitize answer.text before passing it to commands, queries, or downstream tools.

Ask and wait

from jennah import Client
from jennah.approval.v1 import approval_pb2 as ap

with Client() as client:
    created = client.approvals.CreateApproval(
        ap.CreateApprovalRequest(
            request_key="rollout-plan-42",
            kind=ap.APPROVAL_KIND_QUESTION,
            title="Which rollout plan?",
            question=ap.Question(
                choices=[
                    ap.QuestionChoice(
                        id="canary", label="Canary first"),
                    ap.QuestionChoice(
                        id="all", label="All at once"),
                ],
                allow_free_text=True,
            ),
            approvers=[
                ap.ApproverSpec(email="dana@acme.example"),
            ],
        ))
    wait = ap.WaitApprovalRequest(
        approval_id=created.approval.approval_id)

    # Each wait returns within 30 seconds; call again
    # while the question is pending.
    res = client.approvals.WaitApproval(wait)
    while res.timed_out:
        res = client.approvals.WaitApproval(wait)

    q = res.approval
    if q.status == ap.APPROVAL_STATUS_ANSWERED:
        print(list(q.answer.choice_ids), q.answer.text)
import { Client } from "jennah-sdk-ts";
import {
  ApprovalKind,
  ApprovalStatus,
} from "jennah-sdk-ts/gen/jennah/approval/v1/approval_pb";

const client = new Client();
const created = await client.approvals.createApproval({
  requestKey: "rollout-plan-42",
  kind: ApprovalKind.QUESTION,
  title: "Which rollout plan?",
  question: {
    choices: [
      { id: "canary", label: "Canary first" },
      { id: "all", label: "All at once" },
    ],
    allowFreeText: true,
  },
  approvers: [{ email: "dana@acme.example" }],
});
const wait = { approvalId: created.approval!.approvalId };

// Each wait returns within 30 seconds; call again
// while the question is pending.
let res = await client.approvals.waitApproval(wait);
while (res.timedOut) {
  res = await client.approvals.waitApproval(wait);
}

const q = res.approval!;
if (q.status === ApprovalStatus.ANSWERED) {
  console.log(q.answer?.choiceIds, q.answer?.text);
}
res, err := jc.Approvals.Create(ctx, &jennah.CreateApprovalRequest{
    RequestKey: "rollout-plan-42",
    Kind:       jennah.ApprovalKind_APPROVAL_KIND_QUESTION,
    Title:      "Which rollout plan?",
    Question: &jennah.Question{
        Choices: []*jennah.QuestionChoice{
            {Id: "canary", Label: "Canary first"},
            {Id: "all", Label: "All at once"},
        },
        AllowFreeText: true,
    },
    Approvers: []*jennah.ApproverSpec{
        {Email: "dana@acme.example"},
    },
})
if err != nil {
    return err
}

// Loops the bounded server-side wait until it resolves.
q, err := jc.Approvals.WaitUntilDecided(ctx,
    res.Approval.ApprovalId)
if err != nil {
    return err
}
if q.Status == jennah.ApprovalStatus_APPROVAL_STATUS_ANSWERED {
    fmt.Println(q.Answer.ChoiceIds, q.Answer.Text)
}

Who may be asked

Members of your enterprise are always addressable.

External approvers (a customer, a partner, an auditor) must appear on your enterprise's approver allowlist by exact address or domain (managed via the Team page, jnh approvals allowlist, or /v1/approvers). Because editing the allowlist requires management permissions, API keys cannot modify it.

Requests referencing unlisted approvers are rejected in full without creating a request or sending emails.

From the terminal:

# List external approver allowlist entries
# (enterprise members do not require entries).
jnh approvals allowlist list

# Allow a single email address (--kind is required).
jnh approvals allowlist add auditor@partner.com --kind email

# Allow an entire email domain.
jnh approvals allowlist add partner.com --kind domain

# Remove an entry (affects future requests only;
# existing requests keep their links).
jnh approvals allowlist remove <entry-id> --yes

add and remove require approval.approvers:manage, which is a management-class permission and cannot be granted to API keys. Listing the allowlist only requires approval.approvers:read.

Who may decide

Exactly two origins are accepted:

  • the single-use capability token from the emailed link, or
  • an authenticated human who is a listed approver on that request.

API keys can create requests but cannot decide them, even with a valid token.

Decision authority is capability-based, requiring either a single-use token or an authenticated session from a listed approver, and cannot be granted via IAM roles or administrator permissions.

Optional constraints:

  • require_distinct_approver: Prevents the user who created the request from deciding it. Requests that cannot satisfy this constraint are rejected at creation.
  • require_authenticated_decider: Disables token-based link decisions and requires a signed-in session from an enterprise member listed as an approver. Combining it with external approvers is rejected at creation with INVALID_ARGUMENT, because non-members cannot sign in.

The audit record

Every decision is recorded in an append-only log containing the deciding approver (user ID for enterprise members, or email and approver ID for external approvers), the decision, timestamp, optional comment, client IP address, user agent, and a cryptographic digest of the rendered request payload.

Decision records are immutable and cannot be updated or deleted.

Security & threat model

Emailed links contain single-use capability tokens. Anyone with access to the recipient's mailbox (including forwarded addresses or shared inboxes) can authorize the request.

  • Mitigations: Tokens are single-use, expire at the request deadline, are stored as hashes, and record the decider's IP address and user agent.
  • Strict authentication: Enable require_authenticated_decider for high-risk operations to require signed-in authentication.

Token exposure prevention

Tokens are passed in the URL fragment (#t=...), which browsers do not transmit in HTTP requests or Referer headers, keeping them out of web server logs and proxy telemetry.

Automated email scanners and link-rewriting proxies prefetch URLs. Viewing an approval page and submitting a decision are separate steps; HTTP GET requests never record approvals.

Data exposure in payloads

summary and payload content is rendered into email notifications. Do not include sensitive credentials, secrets, or unencrypted personal data in request payloads.

Approval content is mailed exactly as written

Jennah does not scan, filter, or redact summary and payload content on either the email delivery path or the memory write path. Approvers (including external recipients) receive the exact content provided. Treat approval notifications as unfiltered outbound email.

Delivery failures and expiration

If email delivery fails or is delayed beyond the deadline, undecided requests expire as denied (REJECTED or EXPIRED). Check delivery_state or use :resend to handle delivery issues.

When a delivery attempt fails, last_delivery_error is set to one of the following messages. Branch on delivery_state in application code rather than matching the error text.

Cause delivery_state last_delivery_error
Email rendering failure FAILED The approval email could not be prepared because of a problem on the platform's side. Contact support; resending will not help until it is fixed.
Recipient address rejected FAILED The mail provider did not accept this address. Check the address, or name a different approver.
Platform sender failure FAILED The platform could not send email because of a problem on its side. Contact support.
Transient failure (retries remaining) PENDING Email delivery failed temporarily and will be retried automatically.
Transient failure (all 6 attempts exhausted) FAILED Email delivery kept failing temporarily and was stopped after 6 attempts. Resend to try again.

Resending notifications

POST /v1/approvals/{approval_id}:resend re-sends notification emails for pending requests. Earlier links remain functional until a decision is recorded.

# Resend to all pending approvers.
jnh approvals resend <approval-id>

# Resend to a specific approver by ID or email address.
jnh approvals resend <approval-id> --approver auditor@partner.com

The response returns the updated delivery state for each approver. Resent notifications count against monthly email notification quotas.

Cancelling requests

POST /v1/approvals/{approval_id}:cancel cancels a pending request and invalidates all outstanding decision links. Cancelling an already-resolved request returns a FAILED_PRECONDITION error.

Waiting for decisions

POST /v1/approvals/{approval_id}:wait blocks until the request resolves or the server-side wait timeout is reached. If the wait times out while pending, it returns timed_out: true and the request can be polled again.

Each call waits at most 30 seconds. timeout_seconds is clamped to that cap, and 0 (or omitting it) waits the full 30 seconds. To wait longer, call again.

Listing requests

GET /v1/approvals lists requests, newest first. Optional query parameters narrow the listing:

Parameter Effect
status Only requests in this status, e.g. APPROVAL_STATUS_PENDING or APPROVAL_STATUS_ANSWERED
agent_id Only requests naming this agent
only_awaiting_me Only requests waiting on your own decision
request_key_prefix Filter by request_key prefix (case-sensitive, up to 128 bytes)
decided_after Order results by settlement timestamp (oldest first), returning only requests settled after this RFC 3339 timestamp. Cannot be combined with status=APPROVAL_STATUS_PENDING
page_size, page_token Pagination parameters; pass next_page_token from the previous response, or resume_token when polling settled requests

When decided_after (or a settlement resume_token) is used, every response includes resume_token, including the final page and empty pages. When next_page_token is present, both tokens have the same value.

Requests associated with agents outside the caller's selector reach are excluded from results. Authenticated users without approval.requests:read only see requests where they are listed as an approver.

Polling at scale

To poll for newly settled requests without scanning historical records on each poll:

  1. Scope requests to a reachable agent_id and filter by it. Reach checks are applied after database reads, so querying without agent_id using a narrowly scoped API key scans rows the key cannot access.
  2. Prefix request_key values (for example, prism-q-...) and filter with request_key_prefix so filtering happens server-side.
  3. Paginate using resume_token. Pass decided_after on the initial poll, then pass the returned resume_token as page_token on subsequent polls. Each poll returns requests settled since the previous position in ascending settlement order without duplicates, even when older requests settle late or multiple requests settle at the same timestamp.
  4. Persist resume_token durably. The token is the only state required by a poller. If the token is lost, restart from an earlier decided_after timestamp and deduplicate by approval_id.

Expired requests appear in the settlement stream once expiration is processed (typically within one minute of expires_at), ordered by when the expiration was recorded.

# Initial poll: requests settled after the given timestamp
# for this agent and prefix.
curl -sG https://jennah.alphaus.cloud/v1/approvals \
  -H "Authorization: Bearer $JENNAH_API_KEY" \
  -d agent_id=support.bot \
  -d request_key_prefix=prism-q- \
  -d decided_after=2026-11-10T00:00:00Z

# Subsequent polls: page through next_page_token while set,
# then persist resume_token for the next poll cycle.
curl -sG https://jennah.alphaus.cloud/v1/approvals \
  -H "Authorization: Bearer $JENNAH_API_KEY" \
  -d agent_id=support.bot \
  -d request_key_prefix=prism-q- \
  --data-urlencode "page_token=$RESUME_TOKEN"

Keep agent_id, request_key_prefix, and status constant across polls. The token encodes the cursor position rather than the query filters, so changing filters mid-stream applies the new filters starting from the existing cursor position.

Webhook callbacks for settlement events are planned as a push-based alternative to polling.

From the CLI

jnh approvals create --request-key refund-order-1234 \
  --title "Refund order 1234" \
  --approver dana@acme.example --quorum any --ttl 24h
jnh approvals get <approval-id>
jnh approvals list --status pending --awaiting-me
jnh approvals wait <approval-id> --timeout 10m
jnh approvals cancel <approval-id>

jnh approvals ask --request-key rollout-plan-42 \
  --title "Which rollout plan?" \
  --approver dana@acme.example \
  --choice "canary=Canary first: 5% for an hour" \
  --choice "all=All at once" --free-text --wait

ask creates a question request. Each --choice is id=label or id=label: description, kept in the order given; --multi allows more than one, and --free-text allows a free-text response. It takes the same --summary, --payload, --agent, --ttl, --distinct-approver, --require-signin, and --record-to-memory flags as create, but no --quorum or --on-expire. With --wait (or wait on a question), the answer is printed first; -o json returns the approval with its answer.

create also takes --summary, --payload (a JSON object, or @file), --agent, --on-expire deny|expire, --distinct-approver, --require-signin, --record-to-memory, and --wait (with --wait-timeout) to block on the decision in the same command. wait repeats the bounded server-side wait until the request resolves or --timeout (default 10 minutes) elapses. list also accepts --agent, --request-key-prefix, --decided-after (an RFC 3339 timestamp or a relative duration such as 24h), --page-size, and --page-token. When polling settled requests, table output prints the resume token at the end (even when no rows match) so it can be passed to --page-token on the next call, and -o json includes it as resume_token.

get renders the summary's markdown as plain text: headings are underlined, ** and * markers are dropped, lists are re-indented, code blocks are indented, and tables are aligned. Inline code keeps its backticks and strikethrough keeps its ~~. Links print as text <url> and images as [image: alt] <url>. Raw HTML, HTML comments, reference-style links, and any other syntax print as written. The output uses no color, and -o json returns the raw markdown source.

Permissions

Permission What it allows
approval.requests:create Create approval requests and resend notifications
approval.requests:read Read and list all requests in the enterprise (GET, :wait). Not required for requests where the caller is a listed approver
approval.requests:cancel Cancel a pending request
approval.approvers:read Read the external approver allowlist
approval.approvers:manage Modify the external approver allowlist (management-class; cannot be granted to API keys)

Approval permissions are not included in the default member role and must be explicitly granted.

Assigned approvers can view, wait on, list, and decide requests addressed to them without any approval permission. The approval.requests:read permission grants access to all approval requests across the enterprise. An API key is never an approver, so a key needs approval.requests:read to read any request, including ones it raised.

Quotas and limits

Enterprise limits govern concurrent pending requests and monthly notification email volume. Addressing approvers outside your enterprise is a tier-level grant.

Every request is also bounded:

Property Limit
title 256 characters
summary 16000 characters
Approvers per request 25
Duplicate approver emails Not allowed (compared case-insensitively)
Default ttl_seconds 72 hours
Maximum ttl_seconds 30 days
Server-side wait per :wait call 30 seconds
Choices per question 10
Choice id 64 characters: letters, digits, _, ., and -
Choice label 200 characters
Choice description 1000 characters
Answer text 4000 characters

A create that exceeds the title, summary, approver, TTL, or question bound, lists an approver twice, or repeats a choice id, is INVALID_ARGUMENT and rejected in full: nothing is stored and no email is sent. The same applies to a missing request_key, title, or approver. A longer :wait timeout is not refused; it is lowered to the cap.