API Key Resource Bindings

What It Is

This is the canonical architecture for API key scope metadata and bindable resource catalogs. Topolo Auth owns both catalogs. TopoloOne reads both from Auth. Owning applications remain the source of truth for the actual resources.

How It Works

Topolo Auth exposes two route families:

• GET /api/services/:serviceId/api-key-scopes
• GET /api/services/:serviceId/api-key-resources

TopoloOne uses these routes to render the API key form. It does not keep hardcoded scope lists and it does not fetch bindable resources directly from application frontends.

Interfaces

• Auth route registration: Applications/TopoloAuth/src/index.js
• Auth controller methods: Applications/TopoloAuth/src/controllers/auth.js
• Auth repository access: Applications/TopoloAuth/src/repositories/user.js
• TopoloOne client requests: Applications/TopoloOne/apps/dashboard-web/src/lib/api.ts

Data Flow

1. TopoloOne loads service metadata from Auth.
2. TopoloOne requests api-key-scopes for the chosen service.
3. Auth reads service_api_key_scopes from D1.
4. If the service declares resource patterns, TopoloOne requests api-key-resources.
5. Auth discovers the required resource types from service_api_key_scopes.resource_pattern.
6. Auth sync providers refresh the service resource catalog for the current organization.
7. Auth returns active rows from service_api_key_resources.
8. TopoloOne submits the final key payload with resourceBindings.
9. Auth validates and stores the key in api_keys.resource_bindings.

Failure Modes

• service_api_key_scopes has no rows for the selected service
• resource_pattern is missing, so Auth cannot infer bindable resource types
• resource sync provider fails for the service or organization
• service_api_key_resources is empty after sync
• TopoloOne points at the wrong service ID or auth origin
• stale UI code bypasses the Auth-backed API-key endpoints

Debugging

• confirm the service ID in the Auth service registry
• query service_api_key_scopes for the service and verify resource_pattern
• query service_api_key_resources for (service_id, organization_id)
• inspect getServiceApiKeyResources in Auth to see whether sync failed before list
• inspect replaceServiceApiKeyResources, getServiceApiKeyResourceTypes, and listServiceApiKeyResources in the Auth repository
• confirm TopoloOne is calling /api/services/:serviceId/api-key-scopes and /api/services/:serviceId/api-key-resources
• current sync providers cover Socialize brands and Topolo Forecast workspaces, with older code still using the FinSight name in places

Change Log / Verification

• Verified on 2026-03-29 against the live controller and repository implementation
• Canonical D1 tables: service_api_key_scopes, service_api_key_resources, api_keys
• Canonical owning applications for current resource syncs: Socialize and Topolo Forecast