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

# Google Policy Analyzer API

The Google Cloud Policy Analyzer API surfaces activity data that helps organisations understand and right-size their Cloud IAM policies. The single endpoint runs an activities query under a parent organisation, folder, or project, returning records about how IAM permissions and service-account keys have actually been used over a configurable lookback window. Security and compliance teams use that activity data to find unused permissions, dormant service accounts, and over-broad role grants worth removing.

## For AI agents

Query Cloud IAM activity data under an organisation, folder, or project to find unused permissions and service-account keys.

## Scope

Does not modify IAM policies, simulate policy changes, or troubleshoot single access denials - use only to query historical IAM activity records.

## Capabilities

- Query historical IAM activity under an organisation, folder, or project parent
- Identify Cloud IAM permissions granted but never used during the lookback window
- Detect service-account keys that have not been used to authenticate recently
- Filter activity queries by activity type and time range
- Feed least-privilege recommendations into IAM right-sizing workflows

## Use cases

### Least-Privilege IAM Right-Sizing

Cloud security teams query the Policy Analyzer activities endpoint at the organisation level to discover IAM permissions granted to identities but never exercised. The response feeds a quarterly review process that strips unused permissions from custom roles and bindings, shrinking the blast radius of compromised credentials. A typical organisation-wide query covering a 90-day lookback returns within minutes for medium-sized estates.

Example prompt: POST /v1/{parent=organizations/*/locations/*/activityTypes/*}/activities:query with parent set to the org-level resource and capture every activity with empty usage signals to flag for removal.

### Dormant Service-Account Key Detection

Compliance programmes need to retire long-lived service-account keys that no longer authenticate any traffic. The activities query returns records keyed to service-account key activity, letting tools list keys with no recent use across a project or organisation. The output is fed into a key-rotation workflow that disables and then deletes dormant keys.

Example prompt: POST /v1/{parent=projects/*/locations/*/activityTypes/serviceAccountKeyLastAuthentication}/activities:query and disable any key whose lastAuthenticatedTime is older than 90 days.

### Quarterly Compliance Audit Pack

Compliance teams build an evidence pack each quarter showing what IAM activity has occurred under each business-unit folder. The Policy Analyzer query produces the raw activity records, which a downstream report formats per ISO 27001 or SOC 2 control objective. The whole process runs unattended on a schedule and the pack is filed for audit review.

Example prompt: POST /v1/{parent=folders/*/locations/*/activityTypes/*}/activities:query for each business-unit folder over the last 90 days and export the JSON results into the compliance evidence bucket.

### AI Agent IAM Reviews via Jentic

Security automation agents that close the loop between activity data and IAM remediation can call the Policy Analyzer through Jentic without managing OAuth scopes by hand. Jentic stores the audit principal's credentials in its vault and exposes the activities.query operation as a single search-load-execute call, turning a multi-day reporting pipeline into a same-day automation.

Example prompt: Search Jentic for 'find unused Google Cloud IAM permissions', load the activities.query schema, and execute it with the parent resource and a 90-day window.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /v1/{parent}/activities:query | Query IAM activity records under an organisation, folder, or project |

## Key resources

- **activities** — Query historical IAM activity records under an organisation, folder, or project parent

## Why Jentic

- **Setup:** Wiring the Policy Analyzer API by hand means setting up Google Cloud service-account OAuth 2.0, minting scoped tokens, and building the activities query against the parent path on policyanalyzer.googleapis.com yourself. Through Jentic you install once, import the Policy Analyzer API from the API Directory, store the OAuth credential once, and your agent calls it.
- **Permission scoping:** The Policy Analyzer API puts the parent scope in the URL path (/v1/{parent}/activities:query), so a rule can pin your agent to one parent project or organisation: it can query historical IAM activity there and nothing else. That query is the only operation in the allowed set, so the agent reads activity records without changing anything.
- **Credential handling:** Your Google Cloud service-account credential for the Policy Analyzer 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 'find unused IAM permissions', and Jentic returns the activities query operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Google Cloud Policy Simulator API** — Replay past access against a proposed IAM change to predict its effect
- **Google Cloud Policy Troubleshooter API** — Explain why a specific principal got or was denied a specific permission
- **Google Cloud IAM API** — Apply role and binding changes Policy Analyzer recommends

## FAQ

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

It uses OAuth 2.0 with the https://www.googleapis.com/auth/cloud-platform scope and is typically invoked with a service account that has org- or folder-level 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 find unused IAM permissions with this API?

Yes. POST /v1/{parent}/activities:query returns activity records under an org, folder, or project for activity types such as serviceAccountLastAuthentication and serviceAccountKeyLastAuthentication, which downstream tooling uses to flag bindings or keys that have not been used in the lookback window.

### What are the rate limits for the Policy Analyzer API?

The API enforces standard Google Cloud project quotas measured in queries per minute. Org-wide queries are heavier than project-scoped queries, so audit pipelines should batch by folder or project and back off on 429 responses rather than hammering org scope from a single thread.

### How do I run a least-privilege audit through Jentic?

Run jentic search 'find unused Google Cloud IAM permissions', load the schema for POST /v1/{parent}/activities:query, and execute it with the parent resource (organizations/.../locations/global/activityTypes/...) and an optional time-range filter. Jentic handles OAuth and pagination.

### Is the Policy Analyzer API free?

There is no per-call charge for the Policy Analyzer activities query itself. Standard Google Cloud project quotas apply, and some advanced policy intelligence features in adjacent products may require Security Command Center Premium.

### Can I scope queries to a single project rather than the whole organisation?

Yes. The {parent} path parameter accepts organizations/{org}/locations/{loc}, folders/{folder}/locations/{loc}, or projects/{project}/locations/{loc}, so a project-scoped query returns only activity recorded under that project.

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

Yes. Because you run Jentic One yourself, your own rules decide which operations and credentials the agent may use, and the only operation this API exposes is the activities query (POST /v1/{parent}/activities:query), which reads historical IAM activity records without changing anything. Since the parent scope lives in the URL path, you can pin the agent to a single project, folder, or organisation so it can query activity there and nowhere else. Your Google Cloud service-account credential is stored encrypted by your own instance and injected only at call time, never entering the agent's prompt or context.