feat(api): let the provider probe use a stored secret by id

[mmabrouk]

Context

A saved write-only connection needs to be testable without asking the user to type its key again. The probe therefore accepts a Vault secret_id. A managed credential must not use that path because caller-supplied overrides could redirect the credential to another endpoint.

Changes

For ordinary user-owned rows, POST /providers/probe can resolve the stored credential and apply non-secret field overrides as before.

For any row with internal management metadata, the route now returns HTTP 409 before it inspects credentials, merges overrides, or makes an outbound request. The check is about managed lifecycle, not the manager name, so future managers receive the same protection.

The OpenAPI contract includes the probe request and response. The frontend Fern client is regenerated in #6174 and uses this endpoint directly.

Tests / notes

• The focused provider-probe suite passed 93 tests during this slice.
• The final combined API verification passed 229 tests after removing four unsupported write-only webhook compatibility cases.
• The managed regression test proves a caller-supplied URL produces no outbound request.
• Ruff formatting and checks passed.

What to QA

• Probe an ordinary saved write-only connection without retyping the key. Credential and discovery statuses must return normally.
• Probe a managed secret ID with an overridden URL. The API must return 409 and make no outbound request.
• Probe with a missing, cross-project, or mismatched secret. Existing 404, 403, and 422 behavior must remain unchanged.

Depends on #6138 through the credits-starter-seeding base.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview	Aug 23, 2026 2:25pm

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

• New Features

  • Provider connectivity checks can now use securely stored credentials.
  • You can override stored provider credentials or connection details when probing.
  • Stored credentials are scoped to the current project for improved isolation.

• Bug Fixes

  • Added validation for missing provider information and invalid credential references.
  • Prevented switching provider types without supplying compatible replacement credentials.

Walkthrough

Provider probing now accepts either provider kind or a stored secret ID. The router loads project-scoped credentials, applies request overrides, validates provider changes, and invokes the probe service. Tests cover stored credentials, isolation, errors, and validation.

Changes

Stored provider probing

Layer / File(s)	Summary
Probe request contract api/oss/src/apis/fastapi/providers/models.py	ProbeProviderRequest now supports optional kind, secret_id, and provider credential overrides. Validation rejects requests without kind and secret_id.
Stored credential resolution api/oss/src/apis/fastapi/providers/router.py, api/entrypoints/routers.py	ProvidersRouter receives VaultService, loads project-scoped secrets, merges stored and supplied credentials, validates provider-kind changes, and probes with the effective credentials.
Stored probe validation api/oss/tests/pytest/unit/providers/test_provider_probe.py	Tests configure vault data and cover stored credentials, overrides, project isolation, unknown secrets, provider-kind consistency, and missing probe identifiers.

Estimated code review effort: 3 (Moderate) | ~30 minutes

Merge Risk: ⚪ Minimal · up to d5a4d

The change enables stored-secret provider probes while preserving project scoping and credential override behavior. No actionable merge-blocking risk remains; the outbound-credential assertion can be added as routine follow-up.

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant ProvidersRouter
  participant VaultService
  participant ProviderProbeService
  Client->>ProvidersRouter: Submit probe request
  ProvidersRouter->>VaultService: Load project-scoped secret
  VaultService-->>ProvidersRouter: Return stored credentials
  ProvidersRouter->>ProviderProbeService: Probe with merged credentials
  ProviderProbeService-->>Client: Return probe result

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 21.74% which is insufficient. The required threshold is 60.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 23 functions across 4 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The description clearly explains stored-secret probing, managed-secret protection, API behavior, tests, and QA expectations.
Title check	✅ Passed	The title clearly and concisely describes the main change: allowing provider probes to use a stored secret ID.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/provider-probe-stored-key

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[mmabrouk]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

🧹 Nitpick comments (1)

api/oss/tests/pytest/unit/providers/test_provider_probe.py (1)

918-933: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Assert which credential is sent when the caller changes the provider kind.

This test only checks the status code. The security-relevant claim of the guard at api/oss/src/apis/fastapi/providers/router.py lines 93-100 is that a kind change uses the caller's key and never the stored key. Use a Recorder and assert the outbound authorization header, as the neighbouring tests do.

💚 Proposed assertion on the outbound credential

 def test_a_kind_change_is_allowed_when_the_caller_brings_the_credential(monkeypatch):
     vault = _StubVault()
     secret_id = uuid4()
     vault.store(secret_id, PROJECT_ID, _stored_provider_key(kind="openai"))
-    client = build_client(monkeypatch, json_response({"data": []}), vault=vault)
+    recorder = Recorder(json_response({"data": []}))
+    client = build_client(monkeypatch, recorder, vault=vault)
 
     response = client.post(
         "/providers/probe",
         json={
             "secret_id": str(secret_id),
             "kind": "anthropic",
             "provider": {"key": CANARY},
         },
     )
 
     assert response.status_code == 200
+    (sent,) = recorder.requests
+    assert STORED_KEY not in str(sent.headers)

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: dea7d63e-f742-4978-b79a-b8e911aa3349

📥 Commits

Reviewing files that changed from the base of the PR and between a84533a and d5a4d5f.

📒 Files selected for processing (4)

• api/entrypoints/routers.py
• api/oss/src/apis/fastapi/providers/models.py
• api/oss/src/apis/fastapi/providers/router.py
• api/oss/tests/pytest/unit/providers/test_provider_probe.py

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.

[github-actions]

Railway Preview Environment

Status	Destroyed (PR closed)

Updated at 2026-08-23T20:47:19.290Z

[mmabrouk]

lgtm