feat(api): document public API authentication

[KonradStanski]

Summary

This documents authentication for the public Sourcebot API in the generated OpenAPI spec and Mintlify docs.

Changes:

• add public API auth metadata to the OpenAPI document
• document supported auth schemes for external clients
• clarify auth usage in the API reference intro docs
• remove the stale hard-coded version example from the version schema

Details

The spec now documents these auth paths:

• X-Sourcebot-Api-Key: sbk_...
• Authorization: Bearer sbk_...
• Authorization: Bearer sboa_... for EE OAuth access tokens

The API reference docs now lead users to the runtime spec endpoint and explain how auth works for public API consumers.

Testing

• yarn openapi:generate

Notes

• The public API may allow anonymous access depending on instance configuration, so the spec reflects that auth can be optional on some deployments.
• SSE responses are still documented as text/event-stream; OpenAPI does not model typed SSE frames especially well.

Closes #101

Summary by CodeRabbit

• Documentation
  • Added API authentication guide: how to create/use API keys or bearer tokens, and OAuth support on EE instances.
  • Clarified instance-dependent auth behavior, including possible anonymous access.
  • Published API security schemes and global auth options to improve tooling and client generation.
  • Removed an example value from the public version response schema.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 5336b23b-ed2d-40d9-8ca5-3a56523f4dcd

📥 Commits

Reviewing files that changed from the base of the PR and between d07be8c and 9324e51.

📒 Files selected for processing (1)

• docs/api-reference/sourcebot-public.openapi.json

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/api-reference/sourcebot-public.openapi.json

---

Walkthrough

Updated the public OpenAPI document, generation code, and docs to declare bearer and API-key authentication (with a top-level security matrix allowing bearer, API key, or anonymous), added operationId values to seven public endpoints, and removed an example from the version response schema.

Changes

Cohort / File(s)	Summary
OpenAPI spec docs/api-reference/sourcebot-public.openapi.json	Added top-level security entries (allow bearerAuth, sourcebotApiKey, or anonymous); added components.securitySchemes for bearerAuth (HTTP bearer) and sourcebotApiKey (header X-Sourcebot-Api-Key); removed example on PublicVersionResponse.version; added operationIds for several operations.
OpenAPI generation code packages/web/src/openapi/publicApiDocument.ts	Assembled typed components including securitySchemes, injected global security matrix into the generated document, extended info.description with instance-dependent auth details, and added operationId values to public paths (search, streamSearch, listRepositories, getVersion, getFileSource, getFileTree, listFiles).
Schema definitions packages/web/src/openapi/publicApiSchemas.ts	Removed the example metadata from the version field in publicVersionResponseSchema (no shape/signature change).
API docs docs/docs/api-reference/overview.mdx	Added authentication guidance: create API keys and send via X-Sourcebot-Api-Key or Authorization: Bearer; noted some instances may allow anonymous access and EE instances may accept OAuth bearer tokens with sboa_... prefix.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding documentation for public API authentication to the OpenAPI spec.
Linked Issues check	✅ Passed	The PR directly addresses issue #101's core objectives by documenting the REST API surface, defining authentication schemes, and providing usage examples.
Out of Scope Changes check	✅ Passed	All changes are directly related to documenting API authentication and specification—no unrelated modifications detected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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 and usage tips.}