feat: management API surface — adopter-facing CRUD layer alongside buyer-facing AdCP

[bokelley]

Summary

AdCP framework adopters (salesagent, presumably others) ship a buyer-facing surface — AdCP via MCP/A2A — that the framework already nails. They also need an operator-facing management surface for the same per-tenant data: tenants, principals, tokens, products, adapter configs.

Today every adopter writes their own. salesagent has a Flask admin UI with no formal API contract; the next adopter will write something different. The framework could ship a Protocol-based management API that adopters wire to their persistence and get a stable surface for free.

Two surfaces, one philosophy

Super-admin API — global, manages tenants:

```
POST /manage/tenants create
GET /manage/tenants list
GET /manage/tenants/{tenant_id} read
PATCH /manage/tenants/{tenant_id} update (subdomain, ad_server, status)
DELETE /manage/tenants/{tenant_id} deactivate (soft)
POST /manage/tenants/{tenant_id}/domains add a domain alias (multi-domain support)
```

Per-tenant management API — scoped to a tenant:

```
GET /manage/tenants/{tenant_id}/principals
POST /manage/tenants/{tenant_id}/principals
PATCH /manage/tenants/{tenant_id}/principals/{principal_id}
DELETE /manage/tenants/{tenant_id}/principals/{principal_id}
POST /manage/tenants/{tenant_id}/principals/{principal_id}/tokens issue
DELETE /manage/tenants/{tenant_id}/principals/{principal_id}/tokens/{token_id} revoke

GET /manage/tenants/{tenant_id}/products
POST /manage/tenants/{tenant_id}/products
PATCH /manage/tenants/{tenant_id}/products/{product_id}
DELETE /manage/tenants/{tenant_id}/products/{product_id}

GET /manage/tenants/{tenant_id}/adapter
PUT /manage/tenants/{tenant_id}/adapter
```

Three reasons to ship this in the SDK rather than every adopter writing their own:

1. Protocol contract. Today adopters' admin UIs talk directly to ORM. The next time the schema changes, every UI breaks. A management API contract is a stable seam between persistence and operator-facing tooling.
2. Composability. Hosted multi-tenant operators (Scope3 et al.) want to wire their universe directly into the management API of every adopter they host. ScalarFn adoption only happens if there's a stable ScalarFn-side API to call — same logic here.
3. "Headless from day one." The dominant adopter pattern today is "build a CRUD-shaped admin UI to talk to the DB." If the framework ships the API, the UI becomes a thin client to it (and the same UI works across deployments). Adopters who don't need a UI ship operations as direct API calls.

Proposed shape

adcp.management package with:

```python
class TenantStore(Protocol):
"""Adopter-supplied persistence — same shape as MediaBuyStore et al."""
async def create(self, payload: TenantCreate) -> Tenant: ...
async def list(self, *, status: TenantStatus | None = None) -> list[Tenant]: ...
async def get(self, tenant_id: str) -> Tenant | None: ...
async def update(self, tenant_id: str, patch: TenantPatch) -> Tenant: ...
async def deactivate(self, tenant_id: str) -> None: ...
# similar for principals, tokens, products, adapter_config

def make_management_api(
store: TenantStore,
*,
auth: ManagementAuthMiddleware, # super-admin gate
audit_sink: AuditSink | None = None,
) -> ASGIApp: ...
```

The ASGIApp can mount alongside serve()'s buyer-facing app:

```python
buyer_app = build_asgi_app(platform)
management_app = make_management_api(my_store, auth=...)

starlette_app = Starlette(routes=[
Mount("/mcp", app=buyer_app),
Mount("/manage", app=management_app),
])
```

What this unblocks for salesagent specifically

The salesagent admin UI is currently a Flask app speaking directly to ORM. As we kill nginx (in flight) and move to a single-process model, we want to:

1. Stop having an HTML admin UI as the primary management surface — make the management API primary
2. Wire Scope3-side super-admin tooling directly to /manage/tenants/*
3. Eventually rebuild the operator-facing UI as a thin frontend over the management API (or skip it entirely for ops who'd rather use API directly)

This isn't gated on the framework supporting it (we can build management API in salesagent's core/management_api.py), but it'd be much higher leverage if the framework owns the Protocol surface so other adopters benefit.

Adjacent considerations

Auth shape. Super-admin auth is a different beast than buyer auth — typically non-AdCP, often OAuth2 service-account or signed-request tokens scoped per-environment. Worth a parallel ManagementAuthMiddleware Protocol that mirrors BearerTokenAuthMiddleware but with super-admin gate semantics.

Audit. Every management mutation should emit an audit event (who did what, when, on which tenant). The existing AuditSink Protocol fits cleanly — emit on mutation paths.

Spec coordination. Is the management API in scope for the AdCP spec, or strictly a framework adopter convenience? The buyer-facing AdCP is the spec-compliant surface; management is operationally distinct. Lean toward "framework convenience, no spec coordination needed" but worth a sanity check.

Pre-existing salesagent-specific business logic. salesagent has accumulated business logic around proposal manager workflows, governance flows, audit trails. Some of that should land in the framework (proposal manager v1.5 tracks separately at #538); some is salesagent-specific. The management API is a clean place to draw the line — anything in the management API surface is shared across adopters; anything outside is salesagent-private.

Question for the team

Worth scoping in the framework? I'd build it in salesagent first either way (we need it for the headless-API direction this team has been moving toward), but if the framework is open to it I'd happily port the design upstream as a Protocol surface + reference impl in adopter-supplied form.

Context

• salesagent SDK_FEEDBACK round-2 issue series: feat(server): CallableSubdomainTenantRouter for DB-backed tenant lookups #544, feat(auth): header_name + bearer_prefix_required on BearerTokenAuthMiddleware #545, Webhook wiring: boot-time fail-fast + brighter docs when auto_emit_completion_webhooks is on without a sender #546, feat: LazyPlatformRouter for tenant-on-first-request platform construction #547, feat: complete PgBackend for IdempotencyStore (multi-worker durable dedup) #548, feat(testing): build_test_client(platform) — async context manager wrapping lifespan + httpx client #549 (this would be the next one)
• This is more strategic / discussion-shaped than the previous focused asks; use this thread to align on whether it's framework-shaped at all before any implementation.

🤖 Filed via Claude Code

[bokelley]

Triage

Classification: Feature request (RFC/epic-shaped)
Bucket(s): client, signing (no matching labels exist — flagged in run summary)
Status: ready-for-human

What the experts said:

• adtech-product-expert: Adopter-shaped — operator CRUD has no cross-adopter interoperability value; comparable ad-tech management APIs (GAM, TTD) are separate surfaces from protocol SDKs; recommend adcp-management optional package or contrib template instead of core SDK inclusion.
• ad-tech-protocol-expert: Spec-adjacent, not purely framework-convenience — token issuance/revocation routes directly govern the credential lifecycle the AdCP signing spec controls; shipping both a management revocation path and .well-known/governance-revocations.json without a clear authority ordering creates split verification across buyer implementations.
• security-reviewer: Three pre-conditions before this ships as a framework primitive: (1) typed ManagementPrincipal return with role field — a bool-returning auth Protocol lets tenant-A act on tenant-B resources; (2) token issuance explicitly excluded from idempotency replay; (3) structural ASGI isolation preventing buyer-auth middleware from reaching /manage (and vice versa) — this is a footgun in the proposed co-mount pattern.
• dx-expert: Protocol + factory shape is consistent with SDK idioms; the critical unresolved question is whether TenantStore composes with or replaces SubdomainTenantRouter.
• code-reviewer: Split monolithic TenantStore into per-entity protocols (PrincipalStore, TokenStore, etc.) so adopters implement only what they need; Product name collides with existing adcp.Product export; additive and non-breaking as a subpackage.

My take: The packaging decision (framework vs. separate adcp-management package) should be resolved before any implementation work — a separate package keeps core SDK release cadence clean and avoids encoding opinionated admin patterns that diverge per adopter. Regardless of packaging, the token-lifecycle entanglement with AdCP's governance-revocation path needs an explicit authority-ordering decision before any PR.

Tagging @bokelley for architectural call on framework vs. separate package.

---

Triaged by Claude Code. Session: https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}

---

Generated by Claude Code