Approval requirements

An approval requirement turns a require_approval rule into an approval workflow: people your app assigns approve the request in ordered stages before Para signs it. This page defines the approvalRequirement object, its limits, the approval settings your app can adjust without a new policy version, and the lifecycle of the approval case Para opens for each request.

Para turns on approval requirements per API key, so beta and production keys are enabled separately. Until it does, validating or saving a policy with an approvalRequirement fails with permissions_v2_extension_unavailable; contact Para to enable them. Build and test requirements on a beta API key, shown as Development in the Developer Portal, then select Request production review to have Para apply the policy to your production key.

Example

This Guardrail requires two finance approvals for native transfers of 1 ETH or more from app-owned wallets on Base. Transfers of 10 ETH or more also need one executive approval after finance. Treasury admins can change the finance count between 1 and 3 and move the executive threshold between 5 and 20 ETH.

treasury-approvals.json

{
  "id": "treasury-approvals",
  "schemaVersion": "permissions.policy.v1",
  "version": "1",
  "selector": { "walletType": "EVM", "chainId": "8453" },
  "metadata": {
    "productMode": "guardrail",
    "label": "Treasury approvals",
    "description": "Large native transfers need finance approval, and very large ones also need an executive."
  },
  "rules": [
    {
      "id": "approve-large-native",
      "effect": "require_approval",
      "actions": ["transfer_native"],
      "when": { "kind": "compare", "fact": "request.value.baseUnits", "op": "gte", "value": "1000000000000000000" },
      "approvalRequirement": {
        "id": "treasury-review",
        "evidence": "authenticated_approval",
        "amountFact": "request.value.baseUnits",
        "stages": [
          { "id": "finance", "requiredApprovals": 2, "eligibility": [{ "kind": "role", "name": "finance" }] },
          {
            "id": "executive",
            "requiredApprovals": 1,
            "eligibility": [{ "kind": "role", "name": "executive" }],
            "minimumAmount": "10000000000000000000"
          }
        ],
        "configurationManagerEligibility": [{ "kind": "role", "name": "treasury-admin" }],
        "safeKnobs": [
          { "id": "finance-approvals", "kind": "required_approvals", "stageId": "finance", "min": 1, "max": 3 },
          {
            "id": "executive-threshold",
            "kind": "minimum_amount",
            "stageId": "executive",
            "min": "5000000000000000000",
            "max": "20000000000000000000"
          }
        ]
      }
    }
  ]
}

Requirement fields

An approvalRequirement is allowed only on a rule whose effect is require_approval. In a Request, every require_approval rule must have one.

Field	Type	Required	Description
`id`	string	Yes	1 to 64 characters, unique within the policy. Approval settings and cases refer to it.
`stages`	array	Yes	1 to 5 stages with distinct `id`s, run in order. See Stages.
`evidence`	string	No	`authenticated_approval`, the default, or `transaction_signature`. See Evidence.
`amountFact`	string	No	`request.value.baseUnits`, `request.token.value.baseUnits`, `request.safe.value.baseUnits` or `request.safe.token.value.baseUnits`. Required when any stage sets `minimumAmount`, and allowed only then. See Amount bands.
`configurationManagerEligibility`	array	No	1 to 10 eligibility clauses. People who match one can change the adjustable approval settings.
`safeKnobs`	array	No	The adjustable approval settings, at least one, with distinct `id`s. See Adjustable approval settings.

Names, IDs and attribute values are trimmed, and each must be 1 to 64 characters.

Stages

Each stage needs a number of approvals from the people its eligibility selects. The next stage opens only after the current one reaches its count.

Field	Type	Required	Description
`id`	string	Yes	Unique within the requirement.
`requiredApprovals`	integer or `"all"`	Yes	1 to 25, or `"all"` for every person eligible when the stage opens. An `"all"` stage opens only when 1 to 25 people are eligible.
`eligibility`	array	Yes	1 to 10 distinct eligibility clauses.
`minimumAmount`	string	No	The smallest amount, in base units, for which this stage applies. Not allowed on the first stage. See Amount bands.

Each person counts once per case. Someone who approved in one stage is left out of later stages, so a two-stage requirement with two approvals each needs four different people.

Eligibility

A person is eligible for a stage when one of their assignments matches any clause in the stage’s eligibility.

Clause	Shape	Matches
Role	`{ "kind": "role", "name": "finance" }`	A `role` assignment with that name
Attribute equals	`{ "kind": "attribute", "name": "region", "operator": "eq", "value": "eu" }`	An `attribute` assignment with that name and value
Attribute in list	`{ "kind": "attribute", "name": "region", "operator": "in", "values": ["eu", "uk"] }`	An `attribute` assignment with that name and any listed value. `values` holds at least one distinct value.

Names and values must already be in Unicode NFKC form; validation rejects other forms. Your app assigns roles and attributes to users inside an authorization scope, a group name your app chooses, such as one per customer organization. Each wallet that a requirement governs must be bound to an authorization scope, and a stage selects only people assigned in that wallet’s scope. For a wallet without a binding, Para opens no case and the signing request fails with 403 FORBIDDEN and the message wallet has no trusted authorization scope binding. Use replaceUserApprovalAssignments and setWalletAuthorizationScope, listed in the REST SDK Permissions reference.

Assignment	Shape
Role	`{ "kind": "role", "name": "finance" }`
Attribute	`{ "kind": "attribute", "name": "region", "value": "eu" }`

An assignment must use a role name or attribute value that an active policy declares, in a stage, in configurationManagerEligibility or in an eligible_group option. Only users linked to your app, through a wallet connected to it, can receive assignments. For any other user, the call fails with user is not linked to this app.

Amount bands

Amount bands add stages as the amount grows. Set amountFact to the amount to read, and give each stage after the first a minimumAmount.

The first stage has no minimumAmount and applies to every amount the rule’s when matches. In a Guardrail, the amount at which approval starts is therefore fixed, because Guardrail parameters keep their defaults.
Every later stage needs a minimumAmount. The thresholds must be positive, increasing integer strings without leading zeros.
amountFact must be available for every action the rule names. request.value.baseUnits suits transfer_native, and request.token.value.baseUnits suits transfer_tokens. See Facts and conditions.
For Safe payments on execute_safe_transaction and sign_typed_data, use request.safe.value.baseUnits for native payments or request.safe.token.value.baseUnits for ERC-20 payments. Each is present only for its own payment family, so pair it with a rule whose when reads the same family.

Bands are cumulative. A request runs every stage whose minimumAmount it reaches, in order, so in the example a 12 ETH transfer needs finance and then executive approval. If Para cannot read the amount when the request arrives, it does not open a case, and the request fails with approval_amount_unavailable.

Evidence

evidence sets what counts as an approval.

Value	Approval	Requester	Available in
`authenticated_approval`	An eligible person approves while signed in to Para.	Cannot approve or reject their own request.	Guardrail and Request
`transaction_signature`	An eligible person’s wallet signs the transaction itself. Para checks that each signature matches the case’s transaction.	Can add their own signature when eligible.	Request only

In a Request, a rule with authenticated_approval evidence takes effect only after the user consents to the policy, like an allow rule. If the user chose to review each request, the user reviews first, then the case opens.

Requesters

The requester is the person who starts a request. With authenticated_approval evidence, the requester cannot approve their own request. For a user-owned wallet, Para knows the requester: the signed-in user who asked to sign. For an app-owned wallet, the request comes from your app, so pass the ID of the Para user who asked for it as initiatorUserId. The REST signing endpoints and the client SDK signMessage and signTransaction methods for app-owned wallets accept it. The user must be linked to your app, or the request fails with user is not linked to this app. If you omit initiatorUserId, Para has no person to exclude, so any eligible person, including the user who triggered the request, can approve or reject it. When a request names initiatorUserId, Para applies these rules to that requester:

Para leaves the user out of every stage, whatever the evidence.
The user cannot approve or reject the case. A decision fails with INITIATOR_CANNOT_APPROVE or INITIATOR_CANNOT_REJECT, and reading the case as an approver fails with INITIATOR_CANNOT_REVIEW.
The user can cancel the pending case. See Cancelling a case.
Every later attempt of the same request must name the same initiatorUserId.

Adjustable approval settings

safeKnobs declares settings that your app, or a configuration manager, can change after the policy is active without publishing a new version. Each setting targets one stage. A stage can have one participation setting, required_approvals or eligible_group, plus one minimum_amount setting.

`kind`	Fields	Value it takes	Rules
`required_approvals`	`id`, `stageId`, `min`, `max`	An integer from `min` to `max`	`min` and `max` are 1 to 25, and `min` is at most `max`. The stage must use a number for `requiredApprovals`, within that range.
`eligible_group`	`id`, `stageId`, `defaultOptionId`, `options`	The `id` of one option	`options` holds 1 to 25 options with distinct `id`s, each `{ "id", "eligibility" }`. The default option’s `eligibility` must be identical to the stage’s `eligibility`, with the clauses and their keys in the same order.
`minimum_amount`	`id`, `stageId`, optional `min` and `max`	An amount string without leading zeros, from `min` to `max`	The stage must set `minimumAmount`. `min` and `max` are amount strings, `min` is at most `max`, and the stage’s `minimumAmount` must be within the range. Without `max`, the published threshold is the upper bound, so the setting can lower the threshold but not raise it.

Values are saved for one authorization scope, policy version and requirement, as an object of setting id to value, with at most 25 entries. For the example:

{ "finance-approvals": 3, "executive-threshold": "5000000000000000000" }

Your server secret can always write values. A user can write them when one of their assignments in that scope matches configurationManagerEligibility.
An unknown setting id fails with safe_knob_not_declared, and a value of the wrong type or outside its range fails with safe_knob_value_invalid.
Para applies the values and checks the requirement again, so thresholds must stay positive and increasing. A minimum_amount value of "0", or one that is not above the previous stage’s threshold, fails with requirement_schema_invalid.
Changing the values ends open cases for that scope and requirement. See Changes that end open cases.

Limits

These bounds cover requirement structure, saved settings, approver assignments and case lifetime.

Limit	Value
Stages per requirement	5
`requiredApprovals` per stage	25, or `"all"` with at most 25 eligible people
Eligible people when a stage opens	1 to 100, and at least `requiredApprovals`
Eligibility clauses per list	10
`eligible_group` options	25
Saved setting values	25
Assignments per user, across all scopes of one app	25
Distinct role names across active policies	100
Case lifetime	7 days

If the first stage resolves to no eligible people, to fewer than it needs, or to more than 100, Para opens no case and the signing request fails with 400. When a later stage would resolve to more than 100 eligible people, the approval that would open it fails with 400 and the case stays pending. When it would resolve to fewer than it needs, the case ends as invalidated with stage_snapshot_invalid. Permissions errors lists the responses.

Cases

When a require_approval rule with a requirement decides a request, Para opens an approval case and does not sign until the case completes. A REST signing call returns 403 POLICY_REVIEW_REQUIRED with the approvalCaseId. SDK signing with an app-owned wallet throws the same error, and the server SDK and React Native SDK carry the approvalCaseId in error.data. The web and React SDKs currently reject with a generic error that has no data. SDK signing with a user’s wallet holds the request as a pending transaction. See Review required.

Status	Meaning
`pending`	Waiting for approvals.
`completed`	Every stage reached its count. The request can be signed until seven days after the case opened; after that the case still reads `completed` but can no longer authorize signing.
`rejected`	An eligible person rejected the request. One rejection ends the case.
`expired`	The case was still `pending` seven days after it opened.
`cancelled`	Your app or the requester cancelled the case.
`invalidated`	Something the case depends on changed. `terminalReason` says what.

Each stage takes a snapshot of its eligible people when it opens, so assignments added later do not join a stage that is already open. For a readable Safe payment, the case’s request summary includes safePayment: the payment kind, native or erc20, the Safe, the recipient, the amount in base units and the asset, plus from for an ERC-20 transferFrom.

Why a case ends

`terminalReason`	Status	Cause
`rejected_by_eligible_actor`	`rejected`	An eligible person rejected the request.
`case_expired`	`expired`	Seven days passed since the case opened while it was still `pending`.
`case_cancelled`	`cancelled`	Your app or the requester cancelled the case.
`authorization_stack_changed`	`invalidated`	The active policies that decided the request changed.
`authorization_scope_changed`	`invalidated`	The wallet was bound to a different authorization scope.
`requirement_configuration_changed`	`invalidated`	The adjustable approval settings, or the requirement they resolve to, changed.
`requirement_unavailable`	`invalidated`	Para can no longer find or resolve the requirement.
`authority_revoked`	`invalidated`	The assignments behind the open stage changed.
`request_or_requirement_changed`	`invalidated`	The request was evaluated again and now needs a different requirement.
`owner_review_changed`	`invalidated`	The user’s own review of the request is no longer current.
`request_resubmitted`	`invalidated`	The same request was submitted again, and Para opened a new attempt in its place.
`request_allowed_without_approval`	`invalidated`	The same request was later signed without needing this case.
`active_stage_missing`, `stage_snapshot_mismatch`, `stage_snapshot_invalid`, `next_stage_missing`, `next_stage_actor_already_counted`, `next_stage_authority_invalid`, `unexpected_next_stage_snapshot`	`invalidated`	Para could not open or check a stage, for example because the next stage has no eligible people left.

Why a person cannot decide

A case read by a signed-in user includes decision. When canDecide is false, reason is one of:

`reason`	Meaning
`not_eligible`	The person is not in the open stage’s snapshot.
`initiator`	The person is the requester and the evidence is `authenticated_approval`.
`already_decided`	The person already approved or rejected this case.
`case_terminal`	The case is no longer `pending`.
`authority_changed`	The assignments behind the open stage changed.

Cancelling a case

Your server cancels a case with cancelPartnerApprovalCase in the REST SDK, or POST /v1/permissions-v2/approval-cases/{caseId}/cancel. The requester, including a user named in initiatorUserId, cancels it with cancelApprovalCase in the client SDKs. Only a pending case can be cancelled. The case ends with status cancelled and terminalReason case_cancelled. When a pending transaction from a user’s wallet is waiting on the case, Para discards it, so that request never signs. A request that should still go ahead needs a new attempt, which opens a new case. Cancelling a case that is no longer pending fails with 409 CONFLICT.

Changes that end open cases

Para checks these changes against open cases before it applies them:

Replacing, activating or deactivating a policy.
Changing a user’s approval assignments.
Binding a wallet to another authorization scope.
Changing the adjustable approval settings.

An approval case is open while it is pending, and after it completes until it is used to sign or expires. Para refuses a change that would invalidate open cases until you confirm it. A confirmed change ends those cases as invalidated, and their requests need a new attempt.Through the API, a refused change returns 409 with code APPROVAL_CASES_AFFECTED and the case IDs in affectedCaseIds, and nothing changes. To confirm it, send the same change again with force: true.

Matching and single use

A completed case approves one request from one wallet. With authenticated_approval evidence, Para matches the request by its intent and ignores the fields that change when your app rebuilds the transaction:

Request	Fields Para ignores
EVM transaction	`nonce`, the gas limit, and `gasPrice` or `maxFeePerGas` and `maxPriorityFeePerGas`, for the same transaction type
Stellar transaction	The fee, sequence number and signatures, the outer fee of a fee bump, and every precondition: time bounds, ledger bounds, `minSeqNum`, `minSeqAge`, `minSeqLedgerGap` and `extraSigners`
Safe `SafeTx` typed data sent to REST `sign-typed-data`	`nonce`, plus `safeTxGas` and `baseGas` when `gasPrice` is `0`

Other requests, and every request under transaction_signature evidence, must match the approved request exactly. To use the case for a rebuilt transaction, send it as the same request. On REST, reuse the Idempotency-Key header of the first attempt. In the client SDKs, pass the case ID as resumeApprovalCaseId to signMessage or signTransaction. A case can be used once, within seven days of when it opened. Para reserves the case when signing starts and consumes it when the signature is produced, so signing the same request again needs a new case. Once signing has started with a case, a retry must match the reserved request exactly.

Overview

Client Methods

Actions

React Hooks

Signers & Integrations

Smart Accounts

Wallet Connectors

REST SDK

Types & Configuration

Approval requirements

Example

Requirement fields

Stages

Eligibility

Amount bands

Evidence

Requesters

Adjustable approval settings

Limits

Cases

Cancelling a case

Changes that end open cases

Matching and single use

​Example

​Requirement fields

​Stages

​Eligibility

​Amount bands

​Evidence

​Requesters

​Adjustable approval settings

​Limits

​Cases

​Cancelling a case

​Changes that end open cases

​Matching and single use

Example

Requirement fields

Stages

Eligibility

Amount bands

Evidence

Requesters

Adjustable approval settings

Limits

Cases

Cancelling a case

Changes that end open cases

Matching and single use