Google Policy Troubleshooter API
Browse all Google APIs✓ Official Vendor SpecSecurityComplianceoauth21 EndpointsREST
For Agents
Explain why a Cloud IAM principal is allowed or denied a specific permission on a specific resource, with full per-binding reasoning.
Use for: Explain why a service account is denied a Cloud Storage permission, Check whether a user has compute.instances.start on a specific VM, Diagnose a 403 error from a Google Cloud API call, Verify a custom role still grants the expected permissions
Not supported: Does not modify IAM policies, query historical activity, or simulate proposed policy changes — use only to explain a single Cloud IAM access decision.
The Google Cloud Policy Troubleshooter API explains why a particular Google Cloud principal would be allowed or denied a specific permission on a specific resource. Its single iam:troubleshoot endpoint accepts an AccessTuple of {principal, fullResourceName, permission} and returns the granted access and an explanation that walks through every IAM policy and binding involved in the decision. Platform and security teams use it to debug surprising access-denied errors and to verify least-privilege role design before rollout.
Install Jentic One Beta
Connect the Policy Troubleshooter API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Policy Troubleshooter API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Policy Troubleshooter API.
Evaluate whether a Cloud IAM principal has a specific permission on a specific resource
Return GRANTED, NOT_GRANTED, or UNKNOWN_INFO_DENIED for an AccessTuple
List the policies, bindings, and conditions that contributed to the decision
Diagnose unexpected 'permission denied' errors in Google Cloud workflows
Validate that least-privilege custom roles still grant the access they need to grant
Use Cases
Patterns agents use Policy Troubleshooter API for, with concrete tasks.
★ Diagnose Surprise Access Denials
When a service account starts returning 403 errors against a Google Cloud resource, an SRE calls iam:troubleshoot with the principal, full resource name, and the permission the service is asking for. The response explains exactly which policy or condition is blocking access, removing the guesswork of comparing IAM bindings by hand. A typical investigation that previously took 30 minutes drops to a single API call.
POST /v1/iam:troubleshoot with body {accessTuple: {principal: 'user:alice@example.com', fullResourceName: '//storage.googleapis.com/projects/_/buckets/foo/objects/bar', permission: 'storage.objects.get'}} and return the explanation.
Custom Role Verification
Platform teams refactoring custom roles into a least-privilege model run iam:troubleshoot for representative {principal, resource, permission} tuples to confirm the new role still grants exactly the permissions documented for it. The endpoint returns both the decision and the source binding, so a CI pipeline can fail the role rollout if any expected permission is no longer granted.
For each (principal, resource, permission) test tuple in the role spec, POST /v1/iam:troubleshoot and assert that access=GRANTED.
Help-Desk IAM Triage
Internal cloud help-desks use Policy Troubleshooter to triage tickets like 'I cannot deploy to this project'. The agent runs iam:troubleshoot with the user's email, the project's full resource name, and the permission their command needs (for example run.services.create), and the explanation pinpoints the missing binding or denied condition. The user gets a precise resolution rather than a vague 'check IAM' suggestion.
POST /v1/iam:troubleshoot for the ticket's user, target resource, and required permission, and reply with the missing binding identified in the explanation.
AI Agent IAM Debugging via Jentic
DevOps agents that hit a 403 inside an automated cloud workflow can call Policy Troubleshooter through Jentic to self-diagnose before escalating. Jentic stores the cloud audit credential in its vault and exposes the iam:troubleshoot operation as a single search-load-execute call so the agent receives a structured explanation it can include in its escalation log.
Search Jentic for 'troubleshoot a Google Cloud IAM permission', load the iam.troubleshoot schema, and execute it with the principal, full resource name, and required permission from the failing call.
Key Endpoints
1 endpoints — the google cloud policy troubleshooter api explains why a particular google cloud principal would be allowed or denied a specific permission on a specific resource.
METHOD
PATH
DESCRIPTION
POST
/v1/iam:troubleshoot
Troubleshoot a Cloud IAM access decision for an AccessTuple
POST
/v1/iam:troubleshoot
Troubleshoot a Cloud IAM access decision for an AccessTuple
Why Jentic?
Three things that make agents converge on Jentic-routed access.
Credential isolation
Google Cloud service-account credentials are stored encrypted in the Jentic vault. Agents receive scoped, short-lived access tokens at call time so the service account JSON never enters agent context.
Intent-based discovery
Agents search Jentic with intents like 'diagnose a Google Cloud permission denied' and receive the iam.troubleshoot operation with its full input schema, eliminating manual hunts for AccessTuple shape.
Time to first call
Direct integration: 1-2 days for service-account audit roles, fullResourceName plumbing, and explanation parsing. Through Jentic: under 1 hour.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Policy Troubleshooter API through Jentic.
What authentication does the Policy Troubleshooter 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 policy.troubleshooter audit permissions. Through Jentic the credential is held encrypted in the Jentic vault and a scoped access token is injected at call time.
Can I check a permission on any Google Cloud resource?
Yes. POST /v1/iam:troubleshoot accepts an accessTuple with a fullResourceName covering any GCP resource type, the principal as a user, group, or serviceAccount identifier, and the dotted permission string (for example storage.objects.get). The response returns GRANTED, NOT_GRANTED, or UNKNOWN_INFO_DENIED with the explanation.
What are the rate limits for this API?
The API enforces standard Google Cloud project quotas measured in queries per minute. Each troubleshoot call evaluates the full IAM policy chain for the resource, so heavy use should batch by resource and back off on 429 responses rather than calling per-request from a hot loop.
How do I diagnose a 403 error through Jentic?
Run jentic search 'troubleshoot a Google Cloud IAM permission', load the schema for POST /v1/iam:troubleshoot, and execute it with the principal, fullResourceName, and the permission the failing call needed. The response explains which binding allowed or denied the permission.
Is the Policy Troubleshooter API free?
There is no per-call charge for the Policy Troubleshooter endpoint itself. Standard Google Cloud project quotas apply, and the principal calling the API needs sufficient permissions to read the IAM policies involved in the decision.
Can I see exactly which binding granted or denied a permission?
Yes. The response includes an explainedPolicies array listing each policy considered, the bindings within them, and per-binding reasoning. This makes it possible to identify the exact role binding or IAM condition responsible for a GRANTED or NOT_GRANTED decision.
GET STARTED