create_mandate

Create and register a new legal mandate authorizing an AI agent to act on behalf of a principal.

A mandate defines the legal basis, scope, and duration of an agent's authorization. Each mandate is cryptographically linked to the previous one (SHA-256 chain).

The optional structured perimeter (allowed_actions, forbidden_actions, delegation_allowed, max_delegation_depth, max_amount, period_max_amount, risk_classes) is enforced by issue_action_token: an action outside it gets no token. Without it, the mandate is a free-text scope only.

The principal can sign the mandate with its own Ed25519 key (registered once with register_principal_key): build the exact bytes with prepare_mandate_signature, sign them, and pass principal_signature and signed_at. A principal with a registered key must always sign; the signature is sealed into chain_hash and kept in the Proof Pack.

When a body (committee, board) authorized the agent, its decision goes in metadata under the reserved key "organ_decision": body, title, decided_on (YYYY-MM-DD, not in the future, judged on the registry's UTC date), optional reference, and authorized_personnel (the persons or roles the decision designates), as the compact JSON of OrganDecision.to_metadata_value(). It needs allowed_actions without patterns and is refused on a sub-mandate. It is validated, sealed into chain_hash, and shown by verify_mandate and get_proof.

Args: principal_id: Unique identifier of the principal granting the mandate. Example: "user:audric" or "org:acme-corp" agent_id: Unique identifier of the agent receiving authorization. Example: "agent:korvex-advisor-v1" scope: Human-readable description of what the agent is authorized to do. Example: "Compare and recommend financial products to retail clients" legal_basis_regulation: Name of the regulation or contract granting authority. Example: "EU AI Act Art.26" or "Service Agreement 2026" legal_basis_article: Specific article, clause, or reference number. Example: "Art.26(1)(a)" or "Mandat conseil 2026-042" duration_hours: Duration of the mandate in hours. Max 8760 (1 year). Example: 720 (30 days), 168 (1 week), 24 (1 day) legal_basis_jurisdiction: Jurisdiction code. Default "EU". Example: "EU", "FR", "US" parent_mandate_id: UUID of a parent mandate for sub-delegation chains. The parent (and every mandate above it) must be active and unexpired; the parent must allow delegation and have this mandate's principal_id as its agent_id; the sub-mandate must declare allowed_actions within the parent's, and cannot outlive it. Example: "550e8400-e29b-41d4-a716-446655440000" metadata: Optional dict of string key-value pairs for custom annotations. Example: {"client_ref": "CL-2026-001", "advisor_code": "ADV42"} The key "organ_decision" is reserved (see above). allowed_actions: Action types the agent may request. Dotted lowercase identifiers, "domain." prefix patterns, or "". Example: ["invoice.read", "invoice.pay"] forbidden_actions: Action types the agent may never request (wins over allowed). Example: ["agent.create", "invoice.delete"] delegation_allowed: Whether the agent may grant sub-mandates to other agents. Default False. max_delegation_depth: Optional, with delegation_allowed: how many levels of sub-mandates may exist below this mandate (1 to 16). 1 lets the agent delegate but not its sub-agents. Absent: no limit set by this mandate. Refused with delegation_depth_exceeded. max_amount: Optional ceiling per action, as a plain decimal string with a dot. Example: "500" or "120.50" currency: ISO 4217 code of max_amount. Default "EUR". amount_actions: Action types that move money: they must carry "amount" and "currency" metadata, the amount at or below max_amount. A pattern also reaches its sub-types. Empty means every action. Example: ["invoice.pay"] principal_signature: Base64url Ed25519 signature by the principal of the payload returned by prepare_mandate_signature for these same arguments and signed_at. Required if the principal has a registered key. signed_at: The ISO 8601 timestamp (with timezone) placed in the signed payload. Must be within 15 minutes of the registry clock by default. Example: "2026-10-18T20:30:00+00:00" period_max_amount: Optional cumulative ceiling, same currency and same amount_actions as max_amount: the total of the amounts of the tokens issued under this mandate and every sub-mandate below it, over the last period_days days, stays at or below it. Plain decimal string. Example: "2000" period_days: Length of the rolling window of period_max_amount, in whole days (1 to 366). Required with period_max_amount. Example: 30 risk_classes: Optional risk classes bounding the lifetime of action tokens: each {"name", "actions", "max_token_seconds"}. A class reaches its action patterns and their sub-types; a token for an action it reaches lives at most max_token_seconds (1 to 86400), the shortest class winning, in this mandate and every sub-mandate below it. A class may add "registry_check": true: its tokens then carry amr_registry_check, and the receiver re-checks the registry with check_action_token when it acts. Example: [{"name": "irreversible", "actions": ["invoice.pay"], "max_token_seconds": 30, "registry_check": true}]

Returns: JSON string with keys: status, mandate_id, principal_id, agent_id, scope, perimeter, parent_mandate_id, principal_signature, expires_at, organ_decision, chain_hash. principal_signature is {key_id, signed_at} or null; organ_decision is the recorded decision or null. On error: {"error": "...", "code": "..."} (code present for perimeter, delegation, organ decision and principal signature errors).