canonical: https://jentic.com/apis/googleapis.com/policysimulator

# Google Policy Simulator API

The Google Cloud Policy Simulator API lets administrators model the impact of a proposed IAM policy change before they apply it. Three endpoints support replay workflows: create a Replay under a parent organisation, folder, or project, fetch a single Replay's status and metadata, and list ReplayResults that show how each historical access request would have been decided under the candidate policy. Security and platform teams use simulations to confirm that tightening a role or removing a binding will not break production access.

## For AI agents

Simulate proposed IAM policy changes by replaying past access requests and comparing decisions before applying the change.

## Scope

Does not modify IAM policies, query historical activity, or troubleshoot a single live access denial - use only to create and read IAM Replays.

## Capabilities

- Create a Replay under an organisation, folder, or project to model a candidate IAM policy change
- Fetch the status and metadata of an in-flight or completed Replay
- List per-access ReplayResults showing decision differences between baseline and proposed policies
- Identify previously-allowed accesses that would be denied under a tighter policy
- Confirm that a proposed least-privilege change does not break production traffic

## Use cases

### Pre-Change IAM Validation

Before a platform team removes an over-broad role binding, they create a Replay against the proposed policy to confirm no real access was relying on the removed permissions. The Replay reads recent access logs under the parent, evaluates each request twice, and lists differences. Teams skip the change if differences include traffic from production identities and proceed if the diff is empty.

Example prompt: POST /v1/{parent}/replays with body containing the proposed policy override, then GET /v1/{name} until state=SUCCEEDED, then GET /v1/{parent}/results and report any AccessTuples whose decision flipped from ALLOW to DENY.

### Bulk Custom Role Tightening

Security engineers tightening a custom role across a large organisation use Replay to evaluate the proposed changes against thousands of past access requests in one batch. Per-access ReplayResults pinpoint every identity, resource, and permission whose decision would change, letting the team build a targeted exception list before they roll out the new role definition.

Example prompt: Create a Replay with the tightened custom role, list ReplayResults filtered to decision=DIFFERENT, and aggregate by principal and resource to produce an exception list.

### Audit Evidence for IAM Changes

Compliance programmes require evidence that proposed IAM changes were assessed before they were applied. By creating a Replay per change request and attaching the Replay name and ReplayResults summary to the change ticket, teams produce automated evidence that satisfies SOC 2 and ISO 27001 control objectives without manual screenshots.

Example prompt: On every IAM change request, POST /v1/{parent}/replays with the proposed delta, attach the returned Replay name to the change ticket, and store the SUCCEEDED status as audit evidence.

### AI Agent Policy Modelling via Jentic

Cloud security agents that propose IAM cleanups can call Policy Simulator through Jentic to validate every proposed change before they emit a write. Jentic stores the cloud audit credentials in its vault and exposes the replays.create, replays.get, and results.list operations as three search-load-execute calls so the agent can model, poll, and read results in a single short flow.

Example prompt: Search Jentic for 'simulate a Google Cloud IAM policy change', load the replays.create schema, execute it with the proposed policy, then poll replays.get and list results once succeeded.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /v1/{name} | Get a single Replay by name with status and metadata |
| POST | /v1/{parent}/replays | Create a Replay under an organisation, folder, or project |
| GET | /v1/{parent}/results | List ReplayResults for a completed Replay |

## Key resources

- **replays** — Create and inspect IAM policy Replays under an organisation, folder, or project
- **results** — List per-access ReplayResults showing decision differences between baseline and proposed policies

## Why Jentic

- **Setup:** Wiring the Policy Simulator API by hand means configuring Google Cloud service-account OAuth 2.0, minting scoped tokens, and polling the long-running replay resources against policysimulator.googleapis.com yourself. Through Jentic you install once, import the Policy Simulator API from the API Directory, store the OAuth credential once, and your agent calls it.
- **Permission scoping:** The Policy Simulator API puts the replay resource in the URL path (/v1/{parent}/replays, /v1/{name}), so a rule can pin your agent to one parent scope: it can create replays and read their results there and nothing else. Creating and reading replays are the only operations in the allowed set unless you add more, and they do not change any live IAM policy.
- **Credential handling:** Your Google Cloud service-account credential for the Policy Simulator API is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'simulate a Google Cloud IAM policy change', and Jentic returns the matching replays create, get, or results list operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Google Cloud Policy Analyzer API** — Identify candidate IAM bindings to remove that Policy Simulator then validates
- **Google Cloud Policy Troubleshooter API** — Explain why a specific principal would be allowed or denied a specific permission
- **Google Cloud IAM API** — Apply the IAM change once Policy Simulator confirms it is safe

## FAQ

### What authentication does the Policy Simulator API use?

It uses OAuth 2.0 with the https://www.googleapis.com/auth/cloud-platform scope and is typically called with a service account that has org- or folder-level IAM audit permissions. Through Jentic the credential is held encrypted in your Jentic One instance and a scoped access token is injected at call time.

### Can I check whether removing a role binding will break access?

Yes. POST /v1/{parent}/replays with the proposed policy override creates a Replay that re-evaluates recent access requests against the candidate policy. GET /v1/{parent}/results then lists every request whose decision changed, so removed bindings that production traffic actually depended on surface as ALLOW-to-DENY flips.

### What are the rate limits for this API?

The API enforces standard Google Cloud project quotas measured in queries per minute. Replays are asynchronous - the create call returns quickly and the heavy work is done server-side, so the practical bottleneck is usually the time the Replay itself takes rather than QPS.

### How do I simulate an IAM change through Jentic?

Run jentic search 'simulate a Google Cloud IAM policy change', load the schema for POST /v1/{parent}/replays, execute it with the proposed policy override, then call /v1/{name} to poll status and /v1/{parent}/results to read the per-access decisions.

### Is the Policy Simulator API free?

There is no per-call charge for creating Replays or reading results. Standard Google Cloud project quotas apply, and Replay execution time depends on the volume of access logs under the chosen parent.

### Can I run a Replay across an entire organisation at once?

Yes. The {parent} path parameter accepts organizations/{org}/locations/{loc}, folders/{folder}/locations/{loc}, or projects/{project}/locations/{loc}. Org-level Replays cover all access logs under the organisation, but they take longer and consume more quota than narrower scopes.

### Can I limit what my agent is allowed to do with the Policy Simulator API?

Yes. Because Jentic One is self-hosted, you set the rules that decide which operations and credentials your agent may use, and the Policy Simulator API puts the replay resource in the URL path (/v1/{parent}/replays and /v1/{name}), so you can pin the agent to a single organisation, folder, or project parent. You can allow only the create-Replay and list-ReplayResults calls, meaning the agent can model a candidate policy and read the decision diffs there and nothing else. None of these operations mutate a live IAM policy, so a scoped agent can validate proposed changes without ever altering production access.