Skip to main content
POST
Replay a trust policy against recorded decisions (historical)
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

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 receives 403. 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 of candidate 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.permissions or any agent field other than agent.agentId gives outcome: "unknown", effect: "unknown" and the field in missingFields.
  • A gateway, environment or workflow_version scope gives missingFields: ["scope.gateway"], ["scope.environment"] or ["scope.workflow_version"]. An agent scope without scopeId gives ["scope.agent"].
A condition on 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

Pass continueCursor 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

Over MCP, 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

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Body

application/json

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.

candidate
object
required
startAt
integer
required
endAt
integer
required
cursor
string
Minimum string length: 1
limit
integer
Required range: 1 <= x <= 100

Response

One historical simulation page

data
object
required

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.

meta
object
required