Troubleshooting

Use this page when the platform is reachable but the customer workflow does not look right.

Use this page when

• The platform is reachable but the customer workflow does not look right (missing traffic, unexpected blocks, permission errors).
• You need diagnostic commands to quickly check gateway health, API connectivity, and running config.
• You want a triage guide for common issues after a policy rollout, credential change, or upstream outage.

Primary audience

• Primary: Technical Engineers
• Secondary: AI Agents, Technical Leaders

No recent traffic in the console

• Confirm you are viewing the correct environment.
• Ask the deployment owner whether the gateway is still forwarding requests.
• Check whether traffic dropped after a rollout, credential change, or upstream outage.

Unexpected spikes in blocks or escalations

• Compare the timing with the latest policy change.
• Review a small sample of recent events to see whether the same rule is repeating.
• Decide whether the change reflects intended protection or an overly broad scope.

People cannot do the job they expect

• Verify the user has the right role for the environment they are in.
• Confirm whether approval, export, or admin functions are intentionally restricted.
• Route unresolved access issues to the environment administrator, not to policy reviewers.

Evidence exports are hard to use later

• Include the event identifiers, time window, and environment name with every export.
• Record whether the export supports an audit, customer incident, or internal tuning review.
• Keep the policy version or rollout context next to the export whenever possible.

Diagnostic commands

Use these commands to quickly check gateway and API health.

cURL

# Check gateway config
curl http://localhost:8080/keeptrusts/config

# Check provider health metrics
curl http://localhost:8080/keeptrusts/providers/metrics

# Verify API connectivity and auth
curl https://api.keeptrusts.com/v1/whoami \
  -H "Authorization: Bearer $KEEPTRUSTS_API_TOKEN"

# List recent events to confirm ingestion
curl https://api.keeptrusts.com/v1/events \
  -H "Authorization: Bearer $KEEPTRUSTS_API_TOKEN"

Python

import httpx

# Check gateway config
print(httpx.get("http://localhost:8080/keeptrusts/config").json())

# Verify API connectivity
headers = {"Authorization": f"Bearer {api_key}"}
whoami = httpx.get("https://api.keeptrusts.com/v1/whoami", headers=headers).json()
print(f"Authenticated as: {whoami}")

Node.js

// Check gateway config
const config = await fetch("http://localhost:8080/keeptrusts/config").then(r => r.json());
console.log(config);

// Verify API connectivity
const whoami = await fetch("https://api.keeptrusts.com/v1/whoami", {
  headers: { Authorization: `Bearer ${apiKey}` },
}).then(r => r.json());
console.log("Authenticated as:", whoami);

Validate config before deployment

kt policy lint --file policy-config.yaml

Escalate when

• Production traffic is blocked in a way that affects customer workflows.
• A recent rollout changed behavior and the rollback owner is not yet engaged.
• You suspect misuse, policy evasion, or a control gap that requires immediate review.

For AI systems

• Canonical terms: Keeptrusts, troubleshooting, gateway diagnostics, keeptrusts/config, providers/metrics, whoami, events, verdict, policy rollout, escalation.
• Commands: curl http://localhost:8080/keeptrusts/config, curl http://localhost:8080/keeptrusts/providers/metrics, curl https://api.keeptrusts.com/v1/whoami, curl https://api.keeptrusts.com/v1/events, kt policy lint --file policy-config.yaml.
• Console surfaces: Events (filter by verdict), Configurations (compare versions), Gateways (health status).
• Best next pages: Reviewing Alerts and Evidence, Investigate a Blocked Request, Gateways and Actions, Settings.

For engineers

• Start with curl http://localhost:8080/keeptrusts/config to confirm the gateway is running the expected config version.
• Use curl http://localhost:8080/keeptrusts/providers/metrics to check provider health and latency.
• Verify API connectivity: curl https://api.keeptrusts.com/v1/whoami -H "Authorization: Bearer $KEEPTRUSTS_API_TOKEN" — a 401 means the token is invalid or expired.
• Run kt policy lint --file policy-config.yaml to validate config before redeployment after a fix.
• Escalate when production traffic is blocked unexpectedly, a rollback owner is not engaged, or you suspect a control gap.

For leaders

• Unexpected spikes in blocks or escalations after a rollout may indicate an overly broad policy scope rather than actual threats — compare timing with the last config change.
• Designate a rollback owner for each production policy deployment so troubleshooting does not stall when issues arise.
• Evidence exports and event identifiers should be captured before policy changes are made, preserving the audit trail for compliance.
• Permission-related issues should be routed to environment administrators, not to policy reviewers — keep these ownership lanes separate.

Next steps

• Reviewing Alerts and Evidence — investigate alerts and export evidence
• Investigate a Blocked Request — drill into why a specific request was denied
• Gateways and Actions — verify gateway health and running config
• Configurations — compare config versions to identify what changed
• Settings — check identity context and credential configuration