agent active Last verified 2026-03-29

API Key Scope Mismatches

Runbook for when TopoloOne or an app shows the wrong API key scopes, no scopes, or unexpected scope drift.

Owners
identity-platform, platform-experience
Source Repos
Applications/TopoloAuth, Applications/TopoloOne
Systems
Topolo Auth, TopoloOne, Topolo Platform
Tags
runbook, api-keys, scopes

What It Is

Use this runbook when the API key form renders no scopes, the wrong scope list, or stale scope data for a registered service.

How It Works

TopoloOne reads API key scopes from Auth. Auth serves those scopes from the checked-in service_api_key_scopes catalog and its D1-backed runtime equivalent.

Interfaces

  • GET /api/services/:serviceId/api-key-scopes
  • Auth scope seed files
  • TopoloOne API client in apps/dashboard-web/src/lib/api.ts

Data Flow

  1. TopoloOne resolves the selected service ID.
  2. TopoloOne requests scopes from Auth.
  3. Auth looks up that service ID in the API key scope catalog.
  4. The UI renders the returned list.

Failure Modes

  • wrong service ID selected or documented
  • Auth has no scope rows for the service ID
  • TopoloOne calls the wrong Auth route
  • stale deploy/bundle still points at old route logic

Debugging

  • verify the service ID in the system registry and machine JSON
  • inspect Applications/TopoloAuth/scripts/seed-service-api-key-scopes.sql
  • inspect Applications/TopoloOne/apps/dashboard-web/src/lib/api.ts
  • verify the live bundle is calling the expected Auth route

Change Log / Verification

  • Verified against the current centralized API key scope model on 2026-03-29