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:
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:
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:
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.
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, andmailtoURLs are rendered as clickable links. Any other destination, includingjavascript:,data:, and relative URLs, is rendered as plain source text. Each link displays its destination host (ormailtoaddress) 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" }]
}
choicesare displayed in the order provided. Each choice specifies anidreturned in the answer, a displaylabel, and an optionaldescription.multi_selectallows selecting multiple choices (requires non-emptychoices). When false or omitted, at most one choice may be selected.allow_free_textallows 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 withINVALID_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
Email link authentication
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_deciderfor 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.
Link prefetching safety
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:
- Scope requests to a reachable
agent_idand filter by it. Reach checks are applied after database reads, so querying withoutagent_idusing a narrowly scoped API key scans rows the key cannot access. - Prefix
request_keyvalues (for example,prism-q-...) and filter withrequest_key_prefixso filtering happens server-side. - Paginate using
resume_token. Passdecided_afteron the initial poll, then pass the returnedresume_tokenaspage_tokenon 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. - Persist
resume_tokendurably. The token is the only state required by a poller. If the token is lost, restart from an earlierdecided_aftertimestamp and deduplicate byapproval_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.