runbook-agent-push-401

type/runbook

Runbook — Integrations API rejects agent push (401 / 403)

Symptoms

  • Daily 21:00 BCA agent run reports HTTP 401 (or 403) from POST /api/integrations/v1/transactions/bulk.
  • Nothing imports; preview also fails.
  • App itself works fine via the browser (signed in via cookie).

Diagnose

# Smoke the endpoint with the current agent token
curl -i -X POST "$APP_URL/api/integrations/v1/transactions/bulk?preview=1" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"transactions": []}'

Expected: 200 with an empty preview. Got 401 → token wrong/expired/missing. Got 403 → token valid but lacks scope or BANK_ACCOUNT_ID env on the agent side doesn't match an existing account.

Fix

  1. Token rotated on the app side but agent still has old one — update the agent's AGENT_TOKEN (or whatever the agent calls it) from a fresh value generated in the app's integrations settings.
  2. Token never set on agent — set AGENT_TOKEN and APP_URL in the agent's environment.
  3. BANK_ACCOUNT_ID mismatch (403) — open the app, copy the BCA account's ID, update agent env.
  4. Endpoint path drift — verify against docs/integrations/ai-agent-push-transactions.md; the route is /api/integrations/v1/transactions/bulk and ?preview=1 for dry-run.

Prevention

  • Document token rotation cadence (currently manual). Consider adding an ADR for this if the agent becomes critical.
  • The agent should log preview-mode dry runs daily even if approve-then-push is gated — surfaces auth failures within a day instead of weeks later.

Related

  • App docs: docs/integrations/ai-agent-push-transactions.md
  • [[Projects/personal-finance-notion/changelog/2026-05-03-integrations-bulk-api|Integrations bulk API changelog]]