Credential troubleshooting

Diagnose provider setup, OAuth callbacks, scoped resolution, rotation, and Resource use from observable symptoms.

Diagnose credentials from the outside in: establish identity, confirm the authored selector, resolve the binding, inspect Credential status, then inspect the provider operation. Do not start by replacing secret material.

Before you begin

Collect the tenant, namespace, Agent and run ID, authenticated customer or principal, logical binding key, Resource CRN, Credential CRN, provider name, and approximate failure time. Do not copy secret values or callback codes into tickets.

Steps

1. Confirm the incoming request authenticated as the expected tenant, customer, and principal.
2. Inspect the Agent's Resource selector and the Resource's Credential slot.
3. In Credentials → Bindings, find the exact target class, key, scope, and owner.
4. Confirm the assignment is enabled and Policy allows binding:use.
5. Open the Credential and inspect status, next renewal, where it is used, recent activity, and version history.
6. Open provider details and confirm its configuration, provisioning behavior, and bootstrap Credential consumers.
7. Correlate the run journal and Credential event time without exposing secret-bearing payloads.

OAuth fails before consent

Check Client ID, authorization origin, callback registration, provider configuration, and bootstrap client secret selection. If the external service reports redirect mismatch, copy the exact callback from the provider setup view.

OAuth returns but remains pending

Check callback state expiry, one-time session status, code exchange outcome, PKCE support, and provider verification. Restart rather than replaying the callback.

The wrong owner has no binding

Confirm whether the selector requires tenant, customer, or principal scope. Customer identity must be mapped by central authentication before customer-scoped resolution. Principal identity is derived from provider and subject. There is no scope fallback.

Rotation fails

Check the active version's expiry, provider-private state, external application status, bootstrap Credential, egress response classification, and verification. For single-use refresh protocols, uncertain exchange requires reconnect.

Verify

Repeat one read-only Resource operation through the same authenticated owner. Confirm the run pins the expected binding revision and that recent Credential activity records the expected version and outcome.

Troubleshooting escalation

Escalate with identifiers, hashes, timestamps, status codes, and redacted provider messages. Never include material, private state, authorization codes, refresh tokens, private keys, or PKCE verifiers.

Next steps

Use States and errors for exact codes and Credential security for safe evidence handling.