feat(AGX1-272): dual-write agent_api_keys to spark-authz behind FGAC flag

[dm36]

Summary

Wires register_resource / deregister_resource into AgentAPIKeysUseCase.create / delete so api_keys get a SpiceDB tuple (with parent_agent edge) on create and have that tuple removed on delete. Companion to the route-migration PR (#252).

scale-agentex is intentionally decoupled from egp-api-backend. The dual-write call is unconditional from this repo. agentex-auth's per-account routing (scaleapi/agentex#353, FGAC_AGENTEX_AUTH_SPARK) decides whether the call lands on Spark AuthZ or falls back to the legacy SGP backend for the caller's account.

Linear ticket: https://linear.app/scale-epd/issue/AGX1-272/fgac-agent-api-key-dual-write-registerderegister-on-createdelete

Cross-repo stack

#	Repo	PR	Purpose	State
1	scaleapi/scaleapi	#144657	sgp-authz 0.6.0 → 0.7.0; parent_resource kwarg	✅ Merged
2	scaleapi/agentex	#354	agentex-auth Port + Spark adapter + HTTP routes (/v1/authz/register, /v1/authz/deregister) + api_key mapping	✅ Merged
2b	scaleapi/agentex	#353	agentex-auth per-account routing via FGAC_AGENTEX_AUTH_SPARK flag	Open (this PR is decoupled from it — works whether #353 lands first or not)
3 (this PR)	scaleapi/scale-agentex	this	scale-agentex use case calling register_resource(parent=agent)	Ready
4	scaleapi/scale-agentex	#252	route-layer FGAC + 404 collapse + two-factor mutations	Stacked on this

Changes

Port + adapter

• src/adapters/authorization/port.py — abstract register_resource(resource, parent=None) and deregister_resource(resource) on AuthorizationGateway.
• src/adapters/authorization/adapter_agentex_authz_proxy.py — POST /v1/authz/register and /v1/authz/deregister to agentex-auth (endpoints exposed by #354).

Service layer

• src/domain/services/authorization_service.py — register_resource / deregister_resource service methods mirror the grant/revoke pattern (principal_context override, _bypass support, parent identity in log line).

Use case

• src/domain/use_cases/agent_api_keys_use_case.py:
  • create calls _register_api_key_in_auth unconditionally; parent=AgentexResource.agent(agent_id) is load-bearing for the SpiceDB cascade.
  • delete (and delete_by_* variants) call _deregister_api_key_from_auth after the Postgres row is gone.
  • Register fails closed (re-raises); deregister is best-effort (logs).
  • The "no creator resolvable" guard (internal-key path with no principal user/service identity) reads from principal_context at call time — no persisted creator columns.

Tests

• tests/integration/services/test_agent_api_key_service_dual_write.py — 6 cases. Mocks the authorization service; asserts the call sequencing inside the use case.
• tests/integration/fixtures/integration_client.py + tests/unit/use_cases/test_agents_api_keys_use_case.py updated for the new constructor signature.

Test plan

• 6 / 6 dual-write integration tests pass locally.
• Parent edge contract pinned: test_create_api_key_calls_register_resource_with_parent asserts parent=AgentexResource.agent(agent.id) is passed on every register call.
• Fail-closed on register failure preserved.
• Best-effort deregister preserved.
• No-creator-resolvable skip path preserved (runtime check, no persistence).
• 4 pre-existing docker-fixture errors in test_agents_api_keys_use_case.py predate this PR (verified via git stash).
• CI: ruff, ruff-format, alembic migration lint.
• End-to-end against a real SpiceDB once exercised in dev via the agentex-auth routing flip.

Diff scope

10 files changed, 55 insertions(+), 368 deletions(-) — net deletion. Earlier iterations had ~370 lines of OSS-coupling that Harvey's review pruned.

Out of scope / follow-ups

• ZedToken plumbing. If a SpiceDB consistency token use case emerges, expose it under a vendor-neutral column name (not spark_authz_zedtoken).
• Audit / backfill for legacy api_keys created before this PR. Tracked separately.
• Other resource types' grant → register_resource swap (task, build, deployment, schedule). Each owns its own follow-up.

Linked: AGX1-272.

Greptile Summary

Wires register_resource / deregister_resource into AgentAPIKeysUseCase.create and delete, so every api_key gets a SpiceDB tuple (with the parent_agent edge) on creation and has it removed on deletion. Registration is fail-closed (raises, blocking the Postgres write); deregistration is best-effort (logs, never blocks the delete). Internal/identity-less paths are skipped with a warning rather than failing.

• Port + adapter (port.py, adapter_agentex_authz_proxy.py): new abstract methods and their HTTP implementations follow the exact pattern of the pre-existing grant/revoke pair.
• Service layer (authorization_service.py): register_resource / deregister_resource mirror grant/revoke — bypass check, principal override via sentinel ..., then gateway delegation.
• Use case (agent_api_keys_use_case.py): pre-generates api_key_id so the same ID is used for both the SpiceDB tuple and the Postgres row; all three delete variants call deregister after the row is gone.
• Tests: six new integration cases cover parent-edge contract, fail-closed register, best-effort deregister, no-creator skip, and delete-by-name deregister; unit fixture updated for the new constructor signature.

Confidence Score: 5/5

Safe to merge — the dual-write is decoupled from egp-api-backend's feature flag, fail-closed on register and best-effort on deregister semantics are correctly implemented, and the SpiceDB parent-agent edge is tested end-to-end.

All three delete variants are wired correctly, the pre-generated api_key_id ensures the same ID lands in both SpiceDB and Postgres, and the bypass / no-creator guards are complementary rather than conflicting. The integration test suite pins the parent-edge contract and the key ordering invariants.

No files require special attention. The only observation is a test-coverage gap in the _principal helper — it always sets service_account_id=None, leaving the service-account-only creation path untested.

Important Files Changed

Filename	Overview
agentex/src/domain/use_cases/agent_api_keys_use_case.py	Core dual-write wiring: unconditional register before DB write (fail-closed), best-effort deregister after delete; no creator guard skips SpiceDB for identity-less internal paths.
agentex/src/domain/services/authorization_service.py	Adds register_resource / deregister_resource service methods that mirror the existing grant/revoke pattern (bypass check, principal override, gateway delegation).
agentex/src/adapters/authorization/adapter_agentex_authz_proxy.py	Adds register_resource / deregister_resource HTTP calls to agentex-auth, consistent serialization pattern with existing grant/revoke methods.
agentex/src/api/routes/agent_api_keys.py	Injects DAuthorizationService into create/delete routes to extract account_id; passes it down to use-case methods for logging context.
agentex/tests/integration/services/test_agent_api_key_service_dual_write.py	New 6-case integration test suite; covers parent-edge contract, fail-closed create, best-effort deregister, no-creator skip, and delete-by-name deregister paths.

Sequence Diagram

sequenceDiagram
    participant Route as API Route
    participant UC as AgentAPIKeysUseCase
    participant AuthSvc as AuthorizationService
    participant GW as AgentexAuthorizationProxy
    participant DB as Postgres

    Note over Route,DB: CREATE flow (fail-closed)
    Route->>UC: create(agent_id, api_key, account_id)
    UC->>DB: get agent (validate exists)
    UC->>UC: generate api_key_id
    UC->>UC: _register_api_key_in_auth()
    UC->>UC: check principal user_id / service_account_id
    alt no creator identity
        UC-->>UC: skip + warning log
    else creator present
        UC->>AuthSvc: "register_resource(resource=api_key, parent=agent)"
        AuthSvc->>AuthSvc: _bypass() check
        alt bypass
            AuthSvc-->>UC: return (no-op)
        else enabled
            AuthSvc->>GW: register_resource(principal, resource, parent)
            GW->>GW: POST /v1/authz/register
            alt SpiceDB error
                GW-->>UC: raise (DB write blocked)
            end
        end
    end
    UC->>DB: repo.create(api_key_entity)
    UC-->>Route: AgentAPIKeyEntity

    Note over Route,DB: DELETE flow (best-effort)
    Route->>UC: delete(id, account_id)
    UC->>DB: repo.get(id)
    UC->>DB: repo.delete(id)
    alt row existed
        UC->>AuthSvc: "deregister_resource(resource=api_key)"
        AuthSvc->>GW: POST /v1/authz/deregister
        alt failure
            GW-->>UC: raise
            UC-->>UC: catch + warning log
        end
    end
    UC-->>Route: None

Loading

Comments Outside Diff (1)

1. agentex/tests/integration/services/test_agent_api_key_service_dual_write.py, line 703-727 (link)

   Missing test for grant-succeeds-but-DB-create-fails (orphan Spark tuple)

   The suite covers grant failure preventing the DB write, but not the reverse: grant succeeding followed by repo.create raising (e.g., a duplicate key or transient DB error). In that case a Spark tuple exists for an api_key_id that never lands in Postgres. Adding a test for this case would make the documented known-limitation explicit and guard against accidental regression if compensating logic is added later.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: agentex/tests/integration/services/test_agent_api_key_service_dual_write.py
   Line: 703-727
   
   Comment:
   **Missing test for grant-succeeds-but-DB-create-fails (orphan Spark tuple)**
   
   The suite covers `grant` failure preventing the DB write, but not the reverse: `grant` succeeding followed by `repo.create` raising (e.g., a duplicate key or transient DB error). In that case a Spark tuple exists for an `api_key_id` that never lands in Postgres. Adding a test for this case would make the documented known-limitation explicit and guard against accidental regression if compensating logic is added later.
   
   How can I resolve this? If you propose a fix, please make it concise.

   

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
agentex/tests/integration/services/test_agent_api_key_service_dual_write.py:526-530
**`_principal` always has `service_account_id=None`, leaving the service-account-only registration path untested**

`_principal` hardcodes `service_account_id=None`, so every test either has a `user_id` (proceed to register) or neither ID (skip). No test exercises the branch where `user_id is None` but `service_account_id` is set — which should also proceed to `register_resource`. Adding a `service_account_id` parameter (defaulting to `None`) would let a single new test case cover that fork without touching the existing ones.

_{Reviews (6): Last reviewed commit: "test(AGX1-272): add AsyncMock for regist..." | Re-trigger Greptile}

[harvhan]

FeatureFlagProvider couples OSS scale-agentex to egp-api-backend. Can we not add feature flag checks in agentex-auth/ inside the register implementation?

[dm36]

updating

[harvhan]

spark_authz_zedtoken is spark-authz specific token and is leaking a proprietary concept into the OSS Postgres schema/entity.

[dm36]

dropping this field

[harvhan]

Are we using creator_user_id / creator_service_account_id anywhere? Is it really something we want to persist in the db?

[dm36]

dropping these fields

[jenniechung]

do we also need to check if the api key exists (self.agent_api_key_repo.get(id=id)) before deleting + calling _deregister_api_key_from_auth, like the other two delete_<> functions added here?

[dm36]

updated

[harvhan]

Now that FF is moved to agentex-auth, do we still need to thread account_id here? Suggest dropping the account_id extraction/threading entirely and letting agentex-auth derive the account_id from the principal. This keeps the SGP-specific field name out of the OSS repo. The only place I see you're actually using account_id is in log extract, which IMO should be dropped as well.

[harvhan]

Should we follow the egp-api-backend's pattern and add compensating deregister if repo.create fails?

[harvhan]

nit: if ItemDoesNotExist, shouldn't we skip repo.delete as well and just return?