Simulate a trust policy
Replay a trust policy against recorded decisions (historical). Requires permissions grants:read, policies:read and audit:read at your acting organization.
v2 compatibility notes
A historical simulation replays facts recorded on past decisions. It is not an authorization, does not predict today’s gates, and reports any fact the record does not hold as unknown.simulateTrustPolicy replays a candidate trust policy, or a stored revision, against the Trust
Fabric decisions recorded for your credential’s acting organization in a time window. Use it to
see how a condition would have matched past decisions before someone saves it in the Console. A
match here doesn’t mean the policy would match today, and nothing you send changes a policy or a
decision.
The request is a read carried in a JSON body. It changes nothing, so it takes no
Idempotency-Key and every call re-checks your permissions.
Who can simulate
Your credential sets the actor and the organization; a credential with no acting organization receives403. Your actor must hold grants:read, policies:read and audit:read at that
organization, checked again on every page. A policyId is also read under the
trust policy catalog rule,
which needs the three permissions at the platform scope or the deployment root.
Only decisions recorded for exactly your acting organization with no private fence are
evaluated. Personal, platform-wide, private-chat and other organizations’ decisions never are, and
neither are client-reported decisions.
Body
Send exactly one ofcandidate or policyId. Any other field returns 400.
What is unknown
A recorded decision holds its agent, the role recorded for it, and its principal’s kind, organization and resolution (only the resolution when the principal resolved to a role default). Anything else isn’t on the record, so the simulation reports it as unknown rather than guessing:- A condition on
gateway.*,tool.*,run.*,action.*,principal.roles,principal.permissionsor any agent field other thanagent.agentIdgivesoutcome: "unknown",effect: "unknown"and the field inmissingFields. - A
gateway,environmentorworkflow_versionscope givesmissingFields: ["scope.gateway"],["scope.environment"]or["scope.workflow_version"]. Anagentscope withoutscopeIdgives["scope.agent"].
principal.personId or principal.servicePrincipalId returns 400. A machine
credential can’t search decisions by a person’s or service principal’s identity.
The page
unavailable coverage includes a decision whose audience is unresolved, such as a legacy record.
The page still returns what it evaluated, but it isn’t proof of what the whole window holds. The
runId names the recorded run. It doesn’t grant access to that run.
Continuing a page
PasscontinueCursor back as cursor with the same candidate or policyId, window and
limit. The cursor is opaque and sealed, and is bound to your credential, its acting
organization, resolutionRevision, the window, limit and the candidate. Any change, a cursor
from another route, or a newer resolution revision returns 400: start again without a cursor.
isDone is true exactly when continueCursor is null. A scan that can’t move on (a source outage, or a position the source can’t page past) ends as done, and coverage says why; an unavailable page is never proof that nothing more exists.
Example
forge_call_operation with operationId simulateTrustPolicy takes the same fields as its input and returns the same data in its body.
See MCP server.Authorizations
Body
- Option 1
- Option 2
Exactly one of candidate (a policy to replay) or policyId (any stored revision, replayed with that revision's fields), the window startAt..endAt in epoch milliseconds (at most 30 days, ending no later than now), and optional limit (1 to 100, default 50) and cursor. No other field is accepted.
Response
One historical simulation page
A historical simulation replays facts recorded on past decisions. It is not an authorization, does not predict today's gates, and reports any fact the record does not hold as unknown. One page of recorded decisions from the credential's acting organization, each with the candidate's outcome (none, match or unknown), its effect and the recorded fields it lacked. summary counts this page; coverage says whether the window was read to the end.

