Decision Grants

​

Why a second credential

​

Declaring that a tool needs a decision

{
  "connector": "acme_kyb",
  "tools": {
    "monitor_delete": {"permission": "delete", "requires_decision": true},
    "case_decision":  {"permission": "write", "requires_decision": true, "four_eyes_on": ["decline"]},
    "payout_release": {"permission": "write", "requires_decision": true, "decision_fields": ["currency"]}
  }
}

​

What a decision grant approves

{"case_id": "case_8841", "action": "case_decision", "decision": "approve", "subject": "gb:00000001"}

​

Who can approve, and how

1. The service administrator allow-lists, per developer, the OpenID Connect identity providers whose users may approve. The developer API key cannot do this.
2. The platform creates a decision request with its API key: the action, the connector, the case version, the memo text and the policy score the approver must review, the manifest’s four_eyes_on, and the agent the decision is for (agentId, its Grantex agent id; grantId, its grant). The response contains approvalPage, a link to the auth service.
3. The approver opens that page in their browser and signs in with an allow-listed identity provider, with a strong method (for example a passkey). The auth service runs the sign-in itself (authorization code with PKCE, state and nonce) and checks step-up from acr / amr and auth_time. The session lives in an HttpOnly cookie on the auth service and lasts for a configured window (one hour by default); no API ever returns it.
4. One click per decision. The page shows the memo, the policy score and the exact action. The approver clicks approve; the auth service measures how long the decision was on screen, refuses approvals faster than a minimum, and mints the decision grant.
5. The agent’s grant token fetches the minted grant. The platform fetches the grants with the grant token of the agent the request names (getGrants / get_grants) and passes them with that agent’s tool call. enforce() (or an MCP server) verifies them and consumes them at the auth service with that agent’s grant token; only then does the call proceed. With the agent binding on (DECISION_GRANT_AGENT_BINDING=true, see Binding decisions to the requesting agent), this is the only way to get them: the developer API key alone never receives a decision grant, GET /v1/decisions/requests/{id} reports decisionGrantsReady and the approvals but not the tokens, and another agent presenting them is refused (wrong_agent).
6. Everything is in the audit chain: who configured the identity provider, each sign-in, the approval (approver, identity provider, authentication method, dwell time, action, memo and policy score hashes), each release of the grants to an agent, consumption, and every refusal.

import type { Grantex } from '@grantex/sdk';

/** Asks for a four-eyes decline for one agent and returns the page to send approvers to. */
export async function requestDecline(
  grantex: Grantex,
  caseId: string,
  caseVersion: string,
  memo: string,
  policyScore: Record<string, unknown>,
  agent: { id: string; grantId: string },
): Promise<string> {
  const request = await grantex.decisions.createRequest({
    action: { case_id: caseId, action: 'case_decision', decision: 'decline', subject: 'gb:00000001' },
    connector: 'acme_kyb',
    caseVersion,
    fourEyesOn: ['decline'], // the manifest's four_eyes_on for this tool
    memo: { content: memo }, // shown to the approver and bound into the grant by hash
    policyScore: { content: policyScore },
    agentId: agent.id, // the Grantex agent id: only its grant token fetches the grants,
    grantId: agent.grantId, // and they are consumed only for this agent and grant
  });
  // Approvers sign in on this page and approve there; the platform cannot approve.
  return String(request['approvalPage']);
}

import type { Grantex } from '@grantex/sdk';

/** The decision grants of a request made for an agent, fetched with that agent's grant token. */
export async function grantsForAgent(grantex: Grantex, requestId: string, agentGrantToken: string): Promise<string[]> {
  // With the binding on, the API key alone never receives them: getRequest
  // reports decisionGrantsReady and no decisionGrants.
  const released = await grantex.decisions.getGrants(requestId, agentGrantToken);
  // Present once fully approved, and only while unspent, unrevoked and unexpired.
  const grants = released['decisionGrants'];
  return Array.isArray(grants) ? grants.map(String) : [];
}

​

The four-eyes model

• The first approval mints a grant marked four_eyes: {approvals_required: 2, position: 1}. Presented alone it is refused (four_eyes_incomplete).
• The second approval is minted only after the first, by a different approver, and names the first (first_jti, first_sub). Approvers are identified by identity provider and subject; the auth service also refuses a second approver with the same verified email (same_approver).
• The call presents both grants. Both are consumed together, or neither is.
• Four eyes is enforced when approving, in offline verification (a grant that says two approvals are needed is never accepted alone, whatever the manifest says) and when consuming.

​

Validity

• it is consumed: one grant authorises one call;
• the case changes: the platform registers a new case version (for example a hash of the evidence behind the decision) and unconsumed grants for the old version are revoked;
• 24 hours pass, or its request expires;
• the request is cancelled.

​

Enforcing

from typing import Any, Dict, List

from grantex import Grantex


def call_case_decision(
    grantex: Grantex,
    grant_token: str,
    decision_grants: List[str],
    tool_call_arguments: Dict[str, Any],
    current_case_version: str,
) -> None:
    """Calls a tool that needs a decision, with the decision grants a person approved."""
    result = grantex.enforce(
        grant_token,
        "acme_kyb",
        "case_decision",
        decision_grants=decision_grants,  # two for a decision listed in four_eyes_on
        arguments=tool_call_arguments,  # the approved action is derived from these
        case_version=current_case_version,  # from your own case state, never from the agent
    )
    if not result.allowed:
        # reason_code is decision_required or decision_invalid; sub_reason says why
        raise PermissionError(f"{result.reason_code}/{result.sub_reason}: {result.reason}")
    # The grants are now spent: result.decision.jtis

import type { Grantex } from '@grantex/sdk';

/** Calls a tool that needs a decision, with the decision grants a person approved. */
export async function callCaseDecision(
  grantex: Grantex,
  grantToken: string,
  decisionGrants: string[],
  toolCallArguments: Record<string, unknown>,
  currentCaseVersion: string,
): Promise<void> {
  const result = await grantex.enforce({
    grantToken,
    connector: 'acme_kyb',
    tool: 'case_decision',
    decisionGrants, // two for a decision listed in four_eyes_on
    arguments: toolCallArguments, // the approved action is derived from these
    caseVersion: currentCaseVersion, // from your own case state, never from the agent
  });
  if (!result.allowed) {
    // reasonCode is decision_required or decision_invalid; subReason says why
    throw new Error(`${result.reasonCode ?? 'denied'}/${result.subReason ?? ''}: ${result.reason}`);
  }
  // The grants are now spent: result.decision?.jtis
}

​

Refusals

​

Rolling out: decisions.required

​

Binding decisions to the requesting agent

• GET /v1/decisions/requests/{id} never returns the grants; it answers decisionGrantsReady and the approvals by jti.
• POST /v1/decisions/requests/{id}/grants (getGrants / get_grants) releases them only against a live grant token of the agent and grant the request names. Every hand-out and every refusal is recorded in the audit chain; if the record cannot be written, nothing is released.
• POST /v1/decisions/consume spends a request’s grants only when a live grant token of that agent and grant accompanies them (grantToken, as for getGrants). The auth service verifies the token itself (signature, expiry, revocation, grant status, developer) and takes the agent and grant from it, never from the body: agentDid, agentId and grantId, when sent, must be that token’s. A missing token, one that is not live, or another agent’s or grant’s, is refused (wrong_agent, 403), and the refusal is recorded with why (token_check) and what the body claimed. A request that names no agent is consumed as before, without a token; a token sent with it must still be live, and its agent is recorded.
• Asking again for the same action and case version while a request is open for another agent or grant is refused (wrong_agent, 409) instead of answering with that request.

1. A decision the platform takes for itself (its request names no agent): consume it by request id, POST /v1/decisions/requests/{id}/consume with the action and case version, in place of reading the grants and presenting them. Use status and the approvals (or decisionGrantsReady once the binding is on) to tell whether it is ready; a consumption that is not ready is refused with unknown_grant or four_eyes_incomplete.
2. A decision for an agent: name the agent (agentId, grantId) when asking for it, fetch the grants with that agent’s grant token (getGrants / get_grants), and consume them with the same grant token (grantToken), as enforce() does. Naming the agent in the body is not enough.
3. Read subReason before the HTTP status when mapping refusals: wrong_agent arrives with 403, which is not an authentication failure.
4. Use an SDK that sends grantToken (this release or later) wherever enforce() or grantexDecisionVerifier consumes decision grants.

​

Operating

• The auth service’s decision endpoints and pages are off until DECISION_GRANTS_ENABLED=true. PUBLIC_BASE_URL must be https and VAULT_ENCRYPTION_KEY set. Configure step-up with DECISION_STEP_UP_AMR / DECISION_STEP_UP_ACR and DECISION_STEP_UP_MAX_AGE_SECONDS, and the minimum dwell time with DECISION_MIN_DWELL_MS. Bind decisions to the requesting agent with DECISION_GRANT_AGENT_BINDING=true (default off; see above).
• Register https://<auth service>/decisions/callback as the redirect URI of each approver identity provider.
• Metrics: grantex_decision_grants_minted_total, grantex_decision_grants_consumed_total, grantex_decision_grants_rejected_total{stage,reason} (stages sign_in, request, approve, release, consume, case) and the grantex_decision_dwell_seconds histogram. Alert when dwell time collapses towards the minimum.

​

What this does and does not protect against