Common Issues

​

401 when requesting a token

1. Check credentials are loaded
   import os
   print("Client ID:", os.environ.get("AGENT_CLIENT_ID", "NOT SET"))
   print("Secret set:", bool(os.environ.get("AGENT_CLIENT_SECRET")))
   
2. Check agent status — go to Agents and find your agent. Status must be Active. Suspended or Revoked agents can’t authenticate.
3. Verify the base URL — make sure you’re not pointing at localhost in production.
4. Check if credentials were rotated — if someone rotated credentials, the old secret is invalid. Rotate again from the agent’s Settings tab.

​

403 — token request denied

1. Check assigned policies — go to Agents → [your agent] → Settings → Policies. No policies = no access.
2. Use the Policy Simulator — go to Policies → [your policy] → Simulate and test the exact request.
3. Check scope format — scopes are case-sensitive and colon-separated:
   ❌ "read"           ← too vague
   ❌ "Stripe:Read"    ← wrong case
   ✅ "stripe:customer:read"
   
4. Check the policy is active — verify Active is on and Shadow Mode is off.

​

Token expired too quickly

# ✅ Good — one client, tokens cached and renewed automatically
client = OculusClient(client_id="...", client_secret="...")

# ❌ Bad — new client every call, no caching
def my_function():
    client = OculusClient(...)  # don't do this

​

Policy changes not taking effect

• The policy is Active (not Shadow Mode)
• The policy is assigned to the agent
• The Rego syntax is valid (use the Preview button)

​

No audit logs visible

• Check the date range — the viewer defaults to the last 24 hours. Expand it.
• Clear filters — active filters may be hiding events.