docs: clarify scoped access token entitlement

[brendan-kellam]

Summary

• add an info callout to the scoped access token create and revoke API pages
• add the same entitlement and contact guidance to the authentication reference
• shorten the create and revoke endpoint descriptions
• regenerate the checked-in OpenAPI specification

Validation

• OpenAPI JSON parses successfully
• yarn workspace @sourcebot/web exec eslint src/openapi/publicApiDocument.ts
• git diff --check

No changelog entry because this is a documentation-only change.

---

Note

Low Risk
Documentation and OpenAPI description changes only; no runtime or auth behavior changes.

Overview
This PR updates scoped access token docs so readers know the feature needs a custom entitlement and how to request it (team@sourcebot.dev).

It adds a shared Mint Info callout via SCOPED_ACCESS_TOKEN_ENTITLEMENT_INFO on create and revoke in publicApiDocument.ts (x-mint), mirrors the same callout in authentication.mdx, and shortens the OpenAPI endpoint descriptions (dropping long auth/repo-validation detail from the spec text). The checked-in sourcebot-public.openapi.json is regenerated to match.

^{Reviewed by Cursor Bugbot for commit 8928f45. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• Documentation
  • Updated scoped access token API documentation with clearer entitlement requirements.
  • Added guidance to contact team@sourcebot.dev for access.
  • Simplified descriptions of token creation and revocation endpoints by removing detailed authentication requirements.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
sourcebot	🟡 Building	–	Aug 13, 2026, 4:49 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[github-actions]

@brendan-kellam your pull request is missing a changelog!

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 813afa36-8f6c-4e1d-b24e-bcbb585a9d7c

📥 Commits

Reviewing files that changed from the base of the PR and between a7df916 and 8928f45.

📒 Files selected for processing (3)

• docs/api-reference/sourcebot-public.openapi.json
• docs/docs/api-reference/authentication.mdx
• packages/web/src/openapi/publicApiDocument.ts

---

Walkthrough

The change updates scoped access token documentation. Endpoint descriptions remove detailed authentication requirements. OpenAPI metadata and authentication documentation now state that access requires a custom entitlement and provide a contact address.

Changes

Scoped access token documentation

Layer / File(s)	Summary
OpenAPI entitlement metadata packages/web/src/openapi/publicApiDocument.ts	Defines a reusable entitlement notice. Applies the notice to scoped access token creation and revocation operations. Simplifies both endpoint descriptions.
Published access documentation docs/api-reference/sourcebot-public.openapi.json, docs/docs/api-reference/authentication.mdx	Adds the custom-entitlement requirement and contact information. Removes detailed authentication and API-key statements from the published endpoint descriptions.

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

Possibly related PRs

• sourcebot-dev/sourcebot#1549: Introduced the scoped access-token entitlement messaging updated by this change.

✨ 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 codex/docs-scoped-token-entitlement

---

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.}