STG-1806 Make model API key optional in OpenAPI

[monadoid]

Summary

• remove ModelApiKey from the server-v3 OpenAPI global security requirement
• update the checked-in v3 OpenAPI spec so Stainless no longer treats model API key as required client auth

Verification

• pnpm --filter @browserbasehq/stagehand-server-v3 run lint
• pnpm --filter @browserbasehq/stagehand-server-v3 run build

---

Summary by cubic

Make the model API key optional by removing ModelApiKey from server v3 OpenAPI global security (STG-1806). Update the spec/generator in @browserbasehq/stagehand-server-v3 and add a patch changeset so Stainless clients no longer require a model key.

• Migration
  • Regenerate clients from the v3 OpenAPI (e.g., Stainless) to drop ModelApiKey as required auth.

^{Written for commit 3c74893. Summary will update on new commits.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 3c74893

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@browserbasehq/stagehand-server-v3	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

✱ Stainless preview builds

This PR will update the stagehand SDKs with the following commit message.

feat: STG-1806 Make model API key optional in OpenAPI

✅ stagehand-openapi studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅

✅ stagehand-ruby studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → build ⏭️ → lint ✅ → test ✅

✅ stagehand-go studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → build ⏭️ → lint ✅ → test ✅

go get github.com/stainless-sdks/stagehand-go@13699f218c42404fd866e5d61f8100dea2cd8a6b

⚠️ stagehand-php studio · code

Your SDK build had at least one "warning" diagnostic.
generate ⚠️ → lint ✅ → test ✅

⚠️ stagehand-typescript studio · code

Your SDK build had at least one "warning" diagnostic.
generate ⚠️ → build ⏭️ → lint ⏭️ → test ✅

✅ stagehand-java studio · conflict

Your SDK build had at least one note diagnostic.

✅ stagehand-kotlin studio · conflict

Your SDK build had at least one note diagnostic.

⚠️ stagehand-csharp studio · code

Your SDK build had at least one "warning" diagnostic.
generate ⚠️ → build ⏭️ → lint ⏭️ → test ✅

⚠️ stagehand-python studio · code

Your SDK build had at least one "warning" diagnostic.
generate ⚠️ → build ⏭️ → lint ⏭️ → test ✅

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-05-07 18:25:06 UTC

[cubic-dev-ai]

No issues found across 3 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant Client as Stainless Client
    participant UI as API Consumer UI
    participant Gateway as Fastify Gateway
    participant Guard as Security Guard
    participant SpecGen as OpenAPI Spec Generator
    participant SpecFile as openapi.v3.yaml
    participant Route as Route Handler V3
    participant ModelAPI as External Model API

    Note over Client,ModelAPI: Runtime Request Flow

    UI->>Gateway: HTTP request with BrowserbaseApiKey & BrowserbaseProjectId
    Gateway->>Guard: Validate security requirements
    alt ModelApiKey NOT required (current state)
        Guard->>Guard: Check BrowserbaseApiKey and BrowserbaseProjectId only
        Guard-->>Gateway: Allowed
        Gateway->>Route: Forward request
        Route->>ModelAPI: Call external model API
        ModelAPI-->>Route: Model response
        Route-->>UI: Response with model data
    else ModelApiKey required (previous state)
        Guard->>Guard: Check BrowserbaseApiKey, BrowserbaseProjectId, and ModelApiKey
        alt Missing ModelApiKey
            Guard-->>Gateway: 401 Unauthorized
            Gateway-->>UI: Error response
        end
    end

    Note over SpecGen,SpecFile: OpenAPI Spec Generation (build-time)

    SpecGen->>SpecFile: Read existing spec
    SpecGen->>SpecFile: Update global security section
    SpecFile->>SpecGen: Updated spec with ModelApiKey removed
    SpecGen-->>Client: Provide updated spec
    Client->>Client: Regenerate client code
    Client-->>UI: Updated SDK without ModelApiKey requirement

    Note over Gateway,Guard: Security Boundary

Loading