Google Policy Troubleshooter API
Browse all Google APIs42
AI ReadinessFoundational (D-)42/100
Official vendor OpenAPI document · agent-readySecurityComplianceoauth21 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://jentic.com/install.sh?src=apis&api=%2Fapis%2Fgoogleapis.com%2Fpolicytroubleshooter" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fgoogleapis.com%2Fpolicytroubleshooter" | 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
Jentic AI Readiness Score
This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.
P
Policy Troubleshooter API
- Foundational (D-)42/100
73
Foundational Compliance56
Developer Experience & Jentic Compatibility19
AI-Readiness & Agent Experience94
Agent Usability63
Security63
AI DiscoverabilityPowered by JenticScoring Framework 1.0.0 | Scoring Engine 0.4.0
Show dimension breakdown
73
Foundational Compliance
Base layer of spec validity and structural soundness.
Grade: A-Signals: 4
94%
Lint Results
Aggregated quality score from linter diagnostics, weighted by severity.
100%
Resolution Completeness
Percentage of `$ref` references that resolve successfully.
0%
Specification Validity
Checks whether the API description parses successfully and conforms to its declared specification (e.g., OpenAPI).
100%
Structural Integrity
Structural correctness score based on schema issues using logarithmic dampening.
56
Developer Experience & Jentic Compatibility
Clarity, completeness, and ingestion readiness for developers and tooling.
Grade: CSignals: 4
0%
Example Density
How richly the API is illustrated with examples.
100%
Example Validity
Percentage of examples that conform to their schemas.
25%
Response Coverage
Percentage of operations with complete response definitions (success, client error, server error).
100%
Tooling Readiness
Health of API ingestion, bundling, and resolution within Jentic pipelines.
19
AI-Readiness & Agent Experience
Semantic breadth, depth, and agent comprehension for AI systems.
Grade: FSignals: 4
76%
Description Coverage
Coverage of descriptions across API elements.
0%
Error Standardization
Coverage of RFC 9457 Problem Details for error responses.
0%
OperationId Quality
Coverage, uniqueness, and casing consistency of operationIds for AI inference.
0%
Summary Coverage
Coverage of summaries across operations/tags/info.
94
Agent Usability
Functional utility, complexity comfort, and AI orchestration readiness.
Grade: A+Signals: 1
94%
Complexity Comfort
Agent comfort level based on API operational and structural complexity.
63
Security
Trust, risk posture, and security compliance.
Grade: B-Signals: 1
62%
Authentication Strength
Average quality of security schemes based on authentication method strength (weakest link for OAuth2).
63
AI Discoverability
Findability, semantic richness, and reasoning readiness.
Grade: B-Signals: 1
62%
Descriptive Richness
Clarity and depth of descriptions across API elements.
Score it yourself
Every API in the directory is allowlisted, so you can re-score it with no key required.
npx @jentic/api-scorecard-cli score <openapi-url>Why Jentic?
What agents get from Jentic-routed access to this vendor.
Setup
Wiring the Policy Troubleshooter API by hand means setting up Google Cloud service-account OAuth 2.0, minting scoped tokens, and assembling the AccessTuple troubleshoot request against policytroubleshooter.googleapis.com yourself. Through Jentic you install once, import the Policy Troubleshooter API from the API Directory, store the OAuth credential once, and your agent calls it.
Permission scoping
The Policy Troubleshooter API exposes a single read endpoint that takes the access tuple in the request body (/v1/iam:troubleshoot), so limit the agent to the operation it needs: explaining one IAM access decision. That read is the only operation in the allowed set, so the agent cannot modify any IAM policy.
Credential isolation
Your Google Cloud service-account credential for the Policy Troubleshooter 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.
Intent-based discovery
Agents search Jentic by intent such as 'diagnose a Google Cloud permission denied', and Jentic returns the iam troubleshoot operation with its input schema so the agent calls the right endpoint without browsing the reference docs.
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 your Jentic One instance 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.
Can I limit what my agent is allowed to do with the Google Cloud Policy Troubleshooter API?
Yes. Because your Jentic One instance is self-hosted, your own rules decide which operations and credentials the agent may use. This API exposes a single read operation, POST /v1/iam:troubleshoot, so you can scope the agent to just that call: explaining one IAM access decision from a principal, resource, and permission access tuple. With only that read in the allowed set, the agent can diagnose a permission but cannot modify any IAM policy or binding.
GET STARTED