feat(openapi): add updateAPIKeyProfiles and loadApiKeyProfileTemplate by suixinio · Pull Request #1617 · looplj/axonhub

suixinio · 2026-05-09T08:10:31Z

Summary

Adds two GraphQL mutations to /openapi/v1/graphql for programmatic LLM API key profile management via service-account keys, mirroring admin's existing capabilities under the OpenAPI design pattern from #637.

updateAPIKeyProfiles(id, input) — integral state replacement of a key's profiles list
loadApiKeyProfileTemplate(input) — append a project's APIKeyProfileTemplate to a target key

Both resolvers are thin pass-throughs to the existing admin biz methods (APIKeyService.UpdateAPIKeyProfiles, APIKeyProfileTemplateService.LoadTemplate) — zero new business logic. Schema, output types, and gqlgen bindings live in the standalone internal/server/gql/openapi module; admin GraphQL is unchanged.

Privacy / scope model

New scopes.APIKeyProjectScopeReadRule scopes API-key-principal reads to the caller's project + required scope. Mounted on both APIKey and APIKeyProfileTemplate Query policies (the only schemas the new mutations read).
scopes.UserProjectScopeReadRule now skips when no user is in context (mirroring UserProjectScopeWriteRule's convention). Without this, the user-rule fires Deny before the API-key rule gets to evaluate. Behavior is identical for legitimate user principals; only the no-user fallthrough changes.

Required scopes for the new mutations: read_api_keys + write_api_keys (write mutates target key, read fetches target/template via biz). Existing createLLMAPIKey only requires write_api_keys.

Frontend compatibility fix

The OpenAPI updateAPIKeyProfiles resolver coerces nil ModelMappings to [] before save. The admin UI's Zod schema strictly requires a non-null array for modelMappings (sibling array fields are .nullable()), so OpenAPI clients omitting the field would otherwise produce rows the UI can't render. Scoped to the OpenAPI resolver because admin GraphQL inputs are validated client-side and never carry nil here.

Known limitation (follow-up)

Mutation responses (including updateAPIKeyProfiles / loadApiKeyProfileTemplate) currently expose key: String! via the OpenAPI APIKey output type. A service account with read_api_keys + write_api_keys could call these mutations on any same-project key id and read its raw bearer in the response. Mitigation (separate CreatedAPIKey for createLLMAPIKey and APIKey without key for management mutations) deferred to a follow-up.

Test plan

go test ./internal/scopes/... — new APIKeyProjectScopeReadRule unit tests pass
go test ./internal/server/gql/openapi/... — 9 new e2e tests pass (happy paths × 3 mutations, cross-project denial × 2, missing-scope denial × 3, modelMappings normalization regression × 1)
go test ./internal/server/biz/... — admin biz tests not regressed by the privacy rule change
go test ./internal/server/gql/... — admin GraphQL resolver tests not regressed
Manual e2e: built Docker image, deployed to staging, exercised all three mutations via curl against /openapi/v1/graphql
Manual e2e: actual LLM call rate-limit verified — quota of 2 requests enforced, returns HTTP 403 with {"error":{"code":"quota_exceeded","message":"requests quota exceeded: 2/2"}} after limit hit
examples/openapi/ rebuilt with genqlient against synced schema; example program compiles

Adds two GraphQL mutations to /openapi/v1/graphql for programmatic LLM API key profile management via service account keys: - updateAPIKeyProfiles: integral state replacement (mirrors admin) - loadApiKeyProfileTemplate: append a project template to a key Both reuse existing admin biz methods directly — zero new business logic. Following the createLLMAPIKey pattern from looplj#637, the OpenAPI schema stays isolated from admin (own gqlgen module, own minimal APIKey output type, scope checks delegated to ent privacy). Privacy model: - New scopes.APIKeyProjectScopeReadRule restricts API-key-principal reads to the caller's project, gated by required scope. Mounted on both APIKey and APIKeyProfileTemplate Query policies so service accounts can resolve the target key and template. - scopes.UserProjectScopeReadRule now skips when no user is in context (matching UserProjectScopeWriteRule's existing convention) so API key principals fall through to APIKeyProjectScopeReadRule instead of being denied at the user-rule layer. Required scopes for the new mutations: read_api_keys + write_api_keys. Frontend compatibility fix: the OpenAPI updateAPIKeyProfiles resolver coerces nil ModelMappings to []. Admin UI's Zod schema strictly requires a non-null array for this single field (sibling array fields are .nullable()), so OpenAPI clients omitting modelMappings would otherwise produce rows the UI can't render. Tests: - internal/scopes: APIKeyProjectScopeReadRule unit tests - internal/server/gql/openapi (new test file): 9 resolver-level e2e tests covering happy paths, cross-project denial, missing-scope denial, and ModelMappings normalization regression Example client (examples/openapi/): - synced server schema, added genqlient operations for new mutations - regenerated client code with Decimal scalar binding - README updated with scope requirements and capability list

gemini-code-assist

Code Review

This pull request introduces new OpenAPI mutations for programmatically managing LLM API keys, including updateAPIKeyProfiles and loadApiKeyProfileTemplate. It updates the GraphQL schema, implements the corresponding resolvers with normalization logic for model mappings, and enhances the privacy layer to allow service accounts to access resources within their own projects. Feedback highlights a security concern regarding the exposure of raw API keys in mutation responses and suggests using explicit denial in privacy rules when required scopes are missing.

gemini-code-assist · 2026-05-09T08:13:00Z

+	return &APIKey{
+		Key:      k.Key,
+		Name:     k.Name,
+		Scopes:   k.Scopes,
+		Profiles: k.Profiles,
+	}


The APIKey type includes the sensitive key field (the raw secret). Since updateAPIKeyProfiles and loadApiKeyProfileTemplate return this type, any service account with read_api_keys and write_api_keys scopes can retrieve the raw secrets of other API keys within the same project. This violates the principle of least privilege. While acknowledged in the PR description as a known limitation, this is a high-severity security risk that should be addressed by using a separate output type (e.g., ManagedAPIKey) that excludes the secret key for non-creation mutations.

gemini-code-assist · 2026-05-09T08:13:00Z

+		if !hasScope(apiKey.Scopes, string(requiredScope)) {
+			return privacy.Skipf("API key %d does not have required scope: %s", apiKey.ID, requiredScope)
+		}


In APIKeyProjectScopeReadRule, if the API key principal is identified but lacks the required scope, it should return privacy.Denyf instead of privacy.Skipf. This ensures that the authorization failure is explicit and consistent with APIKeyScopeQueryRule (line 33) and APIKeyProjectScopeWriteRule (line 96). Using Skipf here might allow the request to proceed if a subsequent rule in the policy accidentally grants access.

Suggested change

if !hasScope(apiKey.Scopes, string(requiredScope)) {

return privacy.Skipf("API key %d does not have required scope: %s", apiKey.ID, requiredScope)

}

if !hasScope(apiKey.Scopes, string(requiredScope)) {

return privacy.Denyf("API key %d does not have required scope: %s", apiKey.ID, requiredScope)

}

greptile-apps · 2026-05-09T08:15:13Z

Greptile Summary

Adds updateAPIKeyProfiles and loadApiKeyProfileTemplate to the OpenAPI GraphQL surface, backed by existing admin biz methods, and introduces a new APIKeyProjectScopeReadRule so service-account API keys can read project-scoped entities during these mutations.

New resolvers: both are thin pass-throughs to APIKeyService.UpdateAPIKeyProfiles and APIKeyProfileTemplateService.LoadTemplate; updateAPIKeyProfiles normalizes nil ModelMappings \u2192 [] to prevent admin UI rendering failures from OpenAPI-produced rows.
Scope/privacy changes: APIKeyProjectScopeReadRule is added to APIKey and APIKeyProfileTemplate query policies; UserProjectScopeReadRule is changed from Denyf to Skipf when no user is in context \u2014 functionally equivalent for all currently affected entities but broadens the fall-through surface for future policy additions.
Test coverage: 9 new E2E tests exercise happy paths, cross-project denial, missing-scope denial, and the modelMappings normalization regression; the real ent privacy layer runs with no bypass.

Confidence Score: 5/5

Safe to merge; the two new mutations are thin pass-throughs with correct project-scoped read guards, and the privacy-layer changes are functionally equivalent for all currently existing entities.

The resolvers delegate entirely to tested biz methods, the new APIKeyProjectScopeReadRule uses Denyf consistently with sibling rules, cross-project and missing-scope denial are covered by E2E tests, and the UserProjectScopeReadRule Deny→Skip change produces the same net result (default deny) for all entities that don’t already have an API-key read rule. The two comments are about a normalization gap in loadApiKeyProfileTemplate and a forward-looking documentation opportunity — neither is a current defect.

No files require special attention; the observations on openapi.resolvers.go and rule_user_project_scope.go are non-blocking.

Important Files Changed

Filename	Overview
internal/server/gql/openapi/openapi.resolvers.go	Adds two new mutations as thin pass-throughs to existing biz services; nil ModelMappings coercion for updateAPIKeyProfiles is correct, but loadApiKeyProfileTemplate lacks the same normalization.
internal/scopes/rule_apikey_scope.go	New APIKeyProjectScopeReadRule correctly scopes API key principals to their own project and uses Denyf when the scope is missing, consistent with sibling rules.
internal/scopes/rule_user_project_scope.go	Deny→Skip change for no-user context applies transitively to all entities using UserProjectScopeReadRule — net behavior unchanged today, with a forward-looking risk.
internal/ent/schema/api_key.go	Adds APIKeyProjectScopeReadRule to the Query policy after UserProjectScopeReadRule so API key principals fall through to project-scoped read access.
internal/ent/schema/api_key_profile_template.go	Adds APIKeyProjectScopeReadRule to allow service account principals to read templates within their project; mirrors the api_key.go change cleanly.
internal/server/gql/openapi/openapi_test.go	9 new E2E tests covering happy paths, cross-project denial, missing-scope denial, and modelMappings normalization regression; real ent privacy layer with no bypass.
internal/scopes/rule_apikey_scope_test.go	Unit tests for the new APIKeyProjectScopeReadRule covering nil key, missing scope, empty scopes, and happy path cases.
internal/server/gql/openapi/openapi.graphql	Schema correctly defines profiles as [APIKeyProfileInput!]! (non-null); previous thread concern about nullable profiles is resolved.
internal/server/gql/openapi/resolver.go	Adds APIKeyProfileTemplateService dependency to Resolver; clean dependency injection following the existing pattern.

Sequence Diagram

sequenceDiagram
    participant Client as OpenAPI Client
    participant GQL as /openapi/v1/graphql
    participant Auth as WithOpenAPIAuth
    participant Policy as Ent Privacy Layer
    participant Biz as Biz Service

    Client->>GQL: mutation updateAPIKeyProfiles(id, input)
    GQL->>Auth: inject APIKey principal into ctx
    Auth-->>GQL: ctx with APIKey + ProjectID
    GQL->>Policy: Query APIKey by id
    Policy->>Policy: UserProjectScopeReadRule → Skip (no user)
    Policy->>Policy: APIKeyProjectScopeReadRule → Allow
    Policy-->>GQL: APIKey entity
    GQL->>GQL: coerce nil ModelMappings → []
    GQL->>Biz: APIKeyService.UpdateAPIKeyProfiles
    Biz->>Policy: APIKeyProjectScopeWriteRule → Allow
    Biz-->>GQL: updated APIKey
    GQL-->>Client: APIKey response

    Client->>GQL: mutation loadApiKeyProfileTemplate(input)
    GQL->>Policy: Query APIKeyProfileTemplate
    Policy->>Policy: UserProjectScopeReadRule → Skip (no user)
    Policy->>Policy: APIKeyProjectScopeReadRule → Allow
    Policy-->>GQL: template entity
    GQL->>Biz: APIKeyProfileTemplateService.LoadTemplate
    Biz-->>GQL: updated APIKey
    GQL-->>Client: APIKey response

_{Reviews (2): Last reviewed commit: "style: gofumpt-fix trailing newline and ..." | Re-trigger Greptile}

Copilot

Pull request overview

This PR extends the OpenAPI GraphQL surface (/openapi/v1/graphql) to support programmatic API key profile management (update/replace profiles and append profile templates) for service-account API keys, aligning with the OpenAPI graph pattern introduced in #637 and reusing existing admin business services.

Changes:

Added OpenAPI GraphQL mutations updateAPIKeyProfiles and loadApiKeyProfileTemplate, plus associated schema/types and resolver wiring.
Introduced APIKeyProjectScopeReadRule and adjusted UserProjectScopeReadRule to allow non-user principals (API keys) to pass through to API-key-based read authorization.
Added OpenAPI end-to-end resolver tests and updated examples/openapi schema + generated client artifacts/documentation.

Reviewed changes

Copilot reviewed 17 out of 18 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
internal/server/gql/openapi/resolver.go	Adds template service dependency to OpenAPI schema wiring.
internal/server/gql/openapi/openapi.resolvers.go	Implements new OpenAPI mutations and APIKey projection helper.
internal/server/gql/openapi/openapi.graphql	Expands OpenAPI schema with profiles/template types and new mutations.
internal/server/gql/openapi/openapi_test.go	Adds E2E-style tests for OpenAPI mutations and authz scenarios.
internal/server/gql/openapi/models_gen.go	Updates generated OpenAPI models to include profiles and new inputs.
internal/server/gql/openapi/graphql.go	Wires new dependency into OpenAPI GraphQL handler.
internal/server/gql/openapi/gqlgen.yml	Adds scalar/model mappings used by the OpenAPI gqlgen module.
internal/server/gql/openapi/generated.go	Regenerates gqlgen bindings for the expanded OpenAPI schema.
internal/scopes/rule_user_project_scope.go	Changes “no user in context” behavior from deny to skip for read rule.
internal/scopes/rule_apikey_scope.go	Adds `APIKeyProjectScopeReadRule` for API-key principals with project scoping.
internal/scopes/rule_apikey_scope_test.go	Adds unit tests for `APIKeyProjectScopeReadRule`.
internal/ent/schema/api_key.go	Adds API-key-principal read rule to APIKey query policy.
internal/ent/schema/api_key_profile_template.go	Adds API-key-principal read rule to template query policy.
examples/openapi/README.md	Documents new mutations, required scopes, and semantics.
examples/openapi/graphql/openapi.graphql	Syncs example schema with backend OpenAPI schema.
examples/openapi/graphql/genqlient.yaml	Updates genqlient bindings for Decimal scalars and formatting.
examples/openapi/graphql/generated.go	Regenerates example Go client for new mutations/types.
examples/openapi/graphql/api_key.graphql	Adds example operations for new mutations.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+// toOpenAPIAPIKey projects the rich ent.APIKey down to the minimal OpenAPI
+// surface — only what programmatic callers need (key/name/scopes/profiles).
+func toOpenAPIAPIKey(k *ent.APIKey) *APIKey {
+	if k == nil {
+		return nil
+	}
+
+	return &APIKey{
+		Key:      k.Key,
+		Name:     k.Name,
+		Scopes:   k.Scopes,
+		Profiles: k.Profiles,
+	}


+
+input UpdateAPIKeyProfilesInput {
+  activeProfile: String!
+  profiles: [APIKeyProfileInput!]


+      - github.com/looplj/axonhub/internal/objects.Decimal
+  DecimalInput:
+    model:
+      - github.com/looplj/axonhub/internal/objects.Decimal


Add id: ID! to the OpenAPI APIKey output so callers can chain createLLMAPIKey into updateAPIKeyProfiles / loadApiKeyProfileTemplate without a separate lookup. Previously the only way to obtain a freshly-created LLM key's id was via admin UI / direct DB access, which programmatic OpenAPI clients don't have access to. Mechanical changes: - openapi.graphql: APIKey gains id field - toOpenAPIAPIKey lifted into a new helper.go file so subsequent gqlgen regenerations don't sweep it into the warning block as unknown code - examples/openapi/graphql: schema mirror synced; api_key.graphql operations now select id; genqlient client regenerated

Address greptile-apps review on PR looplj#1617: P2 — APIKeyProjectScopeReadRule now Denyf (was Skipf) when an API key principal lacks the required scope. Aligns with the explicit-deny contract used by APIKeyScopeQueryRule and APIKeyProjectScopeWriteRule. Skip is reserved for "this rule's principal type doesn't apply"; here the principal IS an API key, just unauthorised. P1 — UpdateAPIKeyProfilesInput.profiles is now non-null ([APIKeyProfileInput!]!). Closes the gap where a client could submit profiles: null and rely on biz validateActiveProfile to reject — failing earlier at the GraphQL parse layer is the safer contract. Diverges from admin's looser type intentionally; admin/openapi schemas are independently versioned.

Copilot AI review requested due to automatic review settings May 9, 2026 08:10

Copilot started reviewing on behalf of suixinio May 9, 2026 08:11 View session

gemini-code-assist Bot reviewed May 9, 2026

View reviewed changes

greptile-apps Bot reviewed May 9, 2026

View reviewed changes

Comment thread internal/server/gql/openapi/openapi.graphql

Comment thread internal/scopes/rule_apikey_scope.go

Copilot AI reviewed May 9, 2026

View reviewed changes

suixinio added 3 commits May 9, 2026 08:35

style: gofumpt-fix trailing newline and field alignment

088671b

looplj merged commit a73bb05 into looplj:unstable May 9, 2026
4 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(openapi): add updateAPIKeyProfiles and loadApiKeyProfileTemplate#1617

feat(openapi): add updateAPIKeyProfiles and loadApiKeyProfileTemplate#1617
looplj merged 4 commits into
looplj:unstablefrom
suixinio:feat/openapi-key-management

suixinio commented May 9, 2026

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

gemini-code-assist Bot May 9, 2026

Uh oh!

gemini-code-assist Bot May 9, 2026

Uh oh!

greptile-apps Bot commented May 9, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

suixinio commented May 9, 2026

Summary

Privacy / scope model

Frontend compatibility fix

Known limitation (follow-up)

Test plan

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot May 9, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot May 9, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot commented May 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Sequence Diagram

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

greptile-apps Bot commented May 9, 2026 •

edited

Loading