Skip to content

🔐 feat: Limit API Key Runs to Their Grants by Default - #18377

Merged
danny-avila merged 1 commit into
devfrom
danny-avila/key-grants-default
Nov 18, 2026
Merged

danny-avila merged 1 commit into
devfrom
danny-avila/key-grants-default

Conversation

@danny-avila

@danny-avila danny-avila commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

#18280 added grants for agent API keys (which MCP servers and tools a run started with a key may use, per agent) and the dialog to make them. It left the switch at owner: unless the operator opts in, a key still reaches every MCP server its owner can.

This PR changes the default of endpoints.agents.remoteApi.integrations.mode to delegated. After it, a run started with a personal API key may use only the MCP tools its owner granted that key for that agent, on every deployment that does not say otherwise.

This is a breaking change, and it is the one PR in this stack to merge deliberately. On upgrade, a key run that used MCP tools yesterday has them refused until two things happen: the operator declares which servers keys may be granted (integrations.resources), and the owner grants the key in Settings → API Keys. A deployment that declares nothing has nothing to grant. To keep the previous behaviour, set mode: owner.

It is separate from #18280 so that it can be merged, held or reverted on its own.

Related to #13824.

How it works

 export function resolveRemoteIntegrations(appConfig?: AppConfig): RemoteIntegrations {
   const integrations = appConfig?.endpoints?.[EModelEndpoint.agents]?.remoteApi?.integrations;
   return {
-    mode: integrations?.mode ?? 'owner',
+    mode: integrations?.mode ?? 'delegated',

Everything that reads the mode goes through that function: the grant step on each remote request, the consent service's limits for keys, and the flag on GET /api/api-keys that makes the "MCP access" button appear.

config loader (packages/api/src/app/loader.ts)
  reportUngrantableKeyRuns
    config mentions interface.remoteAgents or endpoints.agents.remoteApi
    AND mode is not "owner" AND no integrations.resources
      -> warn: key runs cannot use MCP tools; declare servers, or set mode: owner

The warning is limited to deployments whose config mentions the remote API, so one that never uses it is not told about it on every start.

What a caller sees after the change, for a key with no grant: the run starts and answers; each MCP tool call fails with consent_missing and reaches the model as an error tool result, like any failed tool call. Agents with no MCP tools are unaffected.

Type of change

  • Breaking change

Testing

Tested environments/configuration: WSL2, Node.js 24. No external services.

Automated tests:

  • packages/api/src/apiKeys/grants.spec.ts: with no integrations block, or an empty one, the mode is delegated, a key with no grant has its MCP tools refused, and the view offers nothing because nothing is declared; mode: owner leaves the run unrestricted.
  • packages/api/src/app/loader.spec.ts: the warning for a config that uses the remote API and declares no server; no warning when servers are declared, when the mode is owner, or when the config does not mention the remote API.
  • api/server/services/ApiKeys/grants.spec.js: the real wiring leaves a key run untouched under mode: owner.
  • packages/api/src/apiKeys/handlers.spec.ts, api/server/routes/__tests__/apiKeys.spec.js: the key list says grants are in use when the configuration says nothing, and does not under mode: owner.

Reverting the default, and each condition of the warning, fails a test.

The mock e2e lane calls both remote endpoints with a real API key and an agent that has no MCP tools (e2e/specs/mock/scenarios/auth-path-reads.spec.ts). No e2e scenario runs an MCP tool through the remote API, so none covers a refusal.

Performance

Under the new default every request made with a personal key reads the key's grant once when the run starts (one read of the key's document, after the configuration read the request already makes), and each MCP tool call goes through the grant check described in #18280. A background Responses run reads its key once more to learn its kind. Requests for agents with no MCP tools pay the run-start read and nothing per call. Before this PR none of that happened unless the operator set delegated. I did not measure latency before and after.

Risk / compatibility

Existing API integrations that rely on MCP tools stop using them on upgrade until the operator declares servers and owners grant their keys, or the operator sets mode: owner. Nothing in the API response tells the caller why; the model sees the tool error.

Every key request now reads the key's grant, where under owner it read nothing. If that read fails, or the key cannot be found, the request is refused (mcp_reauth_required, 403), not run unrestricted. That includes requests for agents with no MCP tools.

Still not restricted under delegated, as listed in #18280: requests authenticated with an OIDC token, keys issued to an integration (channels), POST /v1/events, and OpenAPI Action credentials.

The warning only reaches operators whose config mentions the remote API. A deployment where only role defaults enable it (admins can use API keys with no config) is not warned.

No stored-data change.

@danny-avila
danny-avila added this pull request to stack #18263 November 18, 2026 11:04
@danny-avila

Copy link
Copy Markdown
Collaborator Author

@codex review 97d60d4

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-18T18:34:19.267209Z 252af07 Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Already looking forward to the next diff.

Reviewed commit: 97d60d4075

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@danny-avila
danny-avila marked this pull request as ready for review November 18, 2026 16:57
Base automatically changed from danny-avila/key-grant-dialog to dev November 18, 2026 17:27
@danny-avila
danny-avila force-pushed the danny-avila/key-grants-default branch from 97d60d4 to 252af07 Compare November 18, 2026 18:32
@danny-avila

Copy link
Copy Markdown
Collaborator Author

@codex review 252af07

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. 👍

Reviewed commit: 252af07604

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@danny-avila

Copy link
Copy Markdown
Collaborator Author

/quality risk scopes=api

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Quality report

Gate: open. The selected checks completed. Scores and risk levels are advisory.

Status: completed (success). Actions run, attempt 1.

  • Commit: 252af0760480d413b9782ed91824b9c3745dc7e0
  • Requested by: @danny-avila
  • Check: risk
  • Scopes: api
  • Static mutants: off (not used by change risk)
  • Change risk: api
  • Mutation testing (experimental, data-schemas only): none

Change risk

Takeaway: Every changed line has a test. Highest CRAP among changed functions: loadCustomConfig at packages/api/src/app/loader.ts:240, CRAP 40.3 with 95% coverage.

Workspace Files measured Incomplete Unavailable Changed lines with no test Highest CRAP
api 2 of 2 0 0 0 40.3

Refactor hints (highest CRAP first)

Function Complexity Coverage CRAP Location
loadCustomConfig 40 95% 40.3 packages/api/src/app/loader.ts:240
reportUngrantableKeyRuns 15 100% 15.0 packages/api/src/app/loader.ts:167
resolveRemoteIntegrations 11 100% 11.0 packages/api/src/apiKeys/grants.ts:44

CRAP = complexity² × (1 − coverage)³ + complexity

Jobs (1)
Check Result
Change risk (api) success

All data (quality-report artifact) · Run page

The gate opens only when the workflow, source selection, tooling verification, and every report job succeed. A report job fails on a failed test in its workspace's own Jest run, a tool error, a job timeout, or an incomplete mutation report, including a mutation shard that reaches its execution budget. A cancelled workflow keeps the gate closed. Scores are advisory. A change-risk file marked incomplete or unavailable, for example by a failed api/ source-alias suite, does not close the gate.

@danny-avila
danny-avila merged commit d24769e into dev Nov 18, 2026
79 checks passed
@danny-avila
danny-avila deleted the danny-avila/key-grants-default branch November 18, 2026 19:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant