Make Swagger UI actually send the x-api-key header

[vernu]

Fixes #154, closes #258.

Root cause

main.ts registered the API key scheme via .addApiKey({...}) without a name, so it ended up in the OpenAPI doc under the default name api_key, and no operation ever referenced it (there was not a single @ApiSecurity in the repo, controllers only carried @ApiBearerAuth). A security scheme that no operation references means Swagger UI renders the Authorize box, stores the key, and never adds the header to any request. That is exactly the behavior reported in #154, and #258 has the full write-up.

Changes

• Name the scheme so it registers as securitySchemes['x-api-key']: .addApiKey({ type: 'apiKey', name: 'x-api-key', in: 'header' }, 'x-api-key')
• Add @ApiSecurity('x-api-key') to every route guarded by AuthGuard (which accepts either a Bearer JWT or an x-api-key), mirroring the existing @ApiBearerAuth placement:
  • class-level on GatewayController, WebhookController, BillingController
  • per-route on AuthController (only the guarded routes; login/register/reset stay public, and verify-email keeps bearer only since it has no guard)
  • SupportController had no swagger auth annotations at all, so customer-support gets both decorators and request-account-deletion (JwtAuthGuard) gets @ApiBearerAuth only

Verification

• pnpm build passes, and all 73 auth-related unit tests pass
• Inspected the compiled decorator metadata: every guarded operation now carries [{"x-api-key":[]},{"bearer":[]}], public routes are unchanged
• To see it live: open Swagger UI, click Authorize, enter an API key, fire any gateway request and watch the x-api-key header go out in devtools

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Improved API documentation for authenticated endpoints across authentication, billing, gateway, support, and webhook services.
  • Clearly documented API-key and bearer-token security requirements in the interactive API reference.
  • Updated the API-key security scheme so references display consistently throughout the documentation.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
textbee	Ready	Preview	Aug 3, 2026 9:32am

[coderabbitai]

📝 Walkthrough

Walkthrough

Swagger now registers the x-api-key scheme with an explicit name and documents API key or bearer authentication on authenticated controller routes.

Changes

Swagger security metadata

Layer / File(s)	Summary
Named API key scheme api/src/main.ts	Swagger registers the x-api-key header scheme under the explicit x-api-key name.
Auth route security metadata api/src/auth/auth.controller.ts	Authenticated profile, password, API-key, onboarding, and email-verification routes document x-api-key support.
Controller security metadata api/src/billing/billing.controller.ts, api/src/gateway/gateway.controller.ts, api/src/support/support.controller.ts, api/src/webhook/webhook.controller.ts	Billing and gateway routes document x-api-key support. Support routes document bearer authentication, with x-api-key also documented for customer support. Webhook routes retain bearer authentication and add x-api-key.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the primary change: Swagger UI now sends the x-api-key header.
Linked Issues check	✅ Passed	The changes name the x-api-key scheme and reference it on the guarded routes required by issues [#154] and [#258].
Out of Scope Changes check	✅ Passed	All modified files support the linked issues by documenting or registering Swagger authentication requirements.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/swagger-x-api-key-scheme

---

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

[coderabbitai]

🧹 Nitpick comments (1)

api/src/main.ts (1)

44-51: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add a Swagger security contract test.

The changed behavior is visible in the generated OpenAPI document. Add a test that asserts components.securitySchemes['x-api-key'] uses an API key in the x-api-key header. Also assert that guarded operations reference this scheme and public auth operations remain unsecured.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@api/src/main.ts` around lines 44 - 51, Add a Swagger/OpenAPI contract test
for the configuration passed to addApiKey, asserting
components.securitySchemes['x-api-key'] is an apiKey scheme located in the
x-api-key header. Also verify guarded operations reference this security scheme
while public authentication operations remain unsecured.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@api/src/main.ts`:
- Around line 44-51: Add a Swagger/OpenAPI contract test for the configuration
passed to addApiKey, asserting components.securitySchemes['x-api-key'] is an
apiKey scheme located in the x-api-key header. Also verify guarded operations
reference this security scheme while public authentication operations remain
unsecured.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 55d135af-7acc-4ac2-856e-824206a23831

📥 Commits

Reviewing files that changed from the base of the PR and between b85908c and 4dd3364.

📒 Files selected for processing (6)

• api/src/auth/auth.controller.ts
• api/src/billing/billing.controller.ts
• api/src/gateway/gateway.controller.ts
• api/src/main.ts
• api/src/support/support.controller.ts
• api/src/webhook/webhook.controller.ts