Troubleshooting access
Identify the missing access layer before broadening permissions
Start with the caller kind, exact workspace/project/resource IDs, operation, response code and retained request/run ID. Separate authentication, authorization, traffic limits, spending limits and runtime failure.
| Symptom | Check |
|---|---|
| 401 | Bearer credential, expiry/revocation or current sign-in |
| Workspace/project unavailable | Correct workspace identity and key project allowlist |
| Tool missing | Current permissions and the endpoint's actual discovered tools |
| Scope denied | Required operation scope; a custom read grant is not that scope |
| Binding read denied | Required named grants on the actual member/key |
| Shared resource denied | Project-restricted key's workspaceResources and matching scopes |
| org:manage rejected on restricted key | Use an unrestricted, deliberately administrative key |
| Policy unavailable | Approved active revision, inherited chain and resource scope |
| Write denied | Mode, actor permission/grant, policy, snapshot and connector support |
| SSO setup denied | Owner identity and configured provider integration |
| Allowed employee still cannot join | Connection active, exact email, provider assignment and DNS/test state |
| Removing allowed email did not remove access | Join permissions and existing membership are separate |
| 429 | Shared/caller request window; honor Retry-After |
| 402 usage_limit_reached | Applicable plan credit exhausted; request limits are unrelated |
| History seems incomplete | Pagination, date period, retention and correct history type |
| Settings unavailable | Read the service error; do not assume disabled/default or zero usage |
Verify a fix
Change only the identified layer through its supported UI/API. Read back the saved settings, retry a bounded allowed request and verify a request that should remain denied. Retain new and original execution IDs to distinguish the fix from cached output.
For a mutation with uncertain effects, establish the original outcome before retrying. An authorization error is not always the same thing as an interrupted request after a provider accepted a write. Follow the operation's receipt/recovery contract.
Escalate with secret-free diagnostics: caller/key ID or prefix, workspace/project/resource IDs, action, timestamp, status/error and relevant retained version/receipt. Never include the raw key, password or provider token.