feat: add repository scoped tokens#1549

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
brendan-kellam merged 6 commits into from
Aug 13, 2026
Merged

feat: add repository scoped tokens #1549

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
cda8c1b
feat: add repository-scoped access tokens
brendan-kellam Aug 6, 2026
2d6c321
chore: add changelog entry for scoped access tokens
brendan-kellam Aug 6, 2026
e0b2171
Merge branch 'main' into sou-1870-scoped-access-tokens
brendan-kellam Aug 6, 2026
cdc2996
feat: scope access tokens by repository ID
brendan-kellam Aug 6, 2026
c9b3cbd
feat: gate scoped access tokens by entitlement
brendan-kellam Aug 6, 2026
e16eee2
Merge remote-tracking branch 'origin/main' into sou-1870-scoped-acces…
brendan-kellam Aug 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Added a manually triggered cloud image release workflow for isolated internal deployments. [#1566](https://github.com/sourcebot-dev/sourcebot/pull/1566)
- Added Prometheus metrics for the web process, served on `WEB_METRICS_PORT` (default `3070`). [#1570](https://github.com/sourcebot-dev/sourcebot/pull/1570)
- Added an `http_request_duration_seconds` metric recording web request latency by route, method, and status. [#1571](https://github.com/sourcebot-dev/sourcebot/pull/1571)
- [EE] Added one-hour repository-scoped access tokens with public mint and revoke APIs. [#1549](https://github.com/sourcebot-dev/sourcebot/pull/1549)

### Fixed
- Fixed the web process being capped at a ~4GiB heap regardless of how much memory the container has, which caused multi-second garbage collection pauses on larger deployments. [#1569](https://github.com/sourcebot-dev/sourcebot/pull/1569)
Expand Down
218 changes: 217 additions & 1 deletion docs/api-reference/sourcebot-public.openapi.json
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -18,6 +18,10 @@
"name": "Git",
"description": "Git history, diff, and file content endpoints."
},
{
"name": "Scoped Access Tokens",
"description": "Mint and revoke short-lived credentials restricted to specific repositories."
},
{
"name": "System",
"description": "System health and version endpoints."
Expand DownExpand Up@@ -1090,6 +1094,63 @@
"$ref": "#/components/schemas/PublicCommitAuthor"
}
},
"PublicCreateScopedAccessTokenResponse": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Identifier used to revoke the token."
},
"token": {
"type": "string",
"pattern": "^sbst_",
"description": "Opaque bearer token. This value is returned only when the token is created."
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"expiresAt": {
"type": "string",
"format": "date-time"
},
"repoIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true
},
"minItems": 1
}
},
"required": [
"id",
"token",
"createdAt",
"expiresAt",
"repoIds"
]
},
"PublicCreateScopedAccessTokenRequest": {
"type": "object",
"properties": {
"repoIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true
},
"minItems": 1,
"description": "Repository IDs to bind to the token. Every ID must identify a repository accessible to the API-key owner."
}
},
"required": [
"repoIds"
],
"additionalProperties": false
},
"PublicEeUser": {
"type": "object",
"properties": {
Expand DownExpand Up@@ -1253,7 +1314,7 @@
"bearerToken": {
"type": "http",
"scheme": "bearer",
"description": "Bearer authentication header of the form `Bearer <token>`, where `<token>` is your API key."
"description": "Bearer authentication header of the form `Bearer <token>`. The token may be a Sourcebot API key, OAuth access token, or scoped access token, subject to endpoint requirements."
},
"apiKeyHeader": {
"type": "apiKey",
Expand DownExpand Up@@ -2266,6 +2327,161 @@
}
}
},
"/api/ee/scoped_access_token": {
"post": {
"operationId": "createScopedAccessToken",
"tags": [
"Scoped Access Tokens"
],
"summary": "Create a scoped access token",
"description": "Creates an opaque bearer token that expires exactly one hour after issuance and is restricted to the requested repositories. Repository IDs are validated atomically against the API-key owner's current access; the request fails if any ID is missing or inaccessible. Repository IDs are returned by GET /api/repos.\n\nThis endpoint requires a Sourcebot API key. Scoped access tokens, OAuth tokens, and browser sessions cannot mint another scoped access token. The returned token is independent of the API key after issuance and cannot be refreshed.",
"security": [
{
"bearerToken": []
},
{
"apiKeyHeader": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicCreateScopedAccessTokenRequest"
}
}
}
},
"responses": {
"201": {
"description": "Scoped access token created. The opaque token value is returned only in this response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicCreateScopedAccessTokenResponse"
}
}
}
},
"400": {
"description": "Invalid request body or repository scope.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiServiceError"
}
}
}
},
"401": {
"description": "Missing or invalid authentication.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiServiceError"
}
}
}
},
"403": {
"description": "The current authentication method is not an API key, or the API-key owner is not permitted to perform this operation.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiServiceError"
}
}
}
},
"500": {
"description": "Unexpected token creation failure.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiServiceError"
}
}
}
}
}
}
},
"/api/ee/scoped_access_token/{id}": {
"delete": {
"operationId": "revokeScopedAccessToken",
"tags": [
"Scoped Access Tokens"
],
"summary": "Revoke a scoped access token",
"description": "Immediately revokes a scoped access token created by the authenticated API-key owner. This endpoint requires a Sourcebot API key.",
"security": [
{
"bearerToken": []
},
{
"apiKeyHeader": []
}
],
"parameters": [
{
"schema": {
"type": "string",
"description": "Identifier returned when the scoped access token was created."
},
"required": true,
"description": "Identifier returned when the scoped access token was created.",
"name": "id",
"in": "path"
}
],
"responses": {
"204": {
"description": "Scoped access token revoked."
},
"401": {
"description": "Missing or invalid authentication.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiServiceError"
}
}
}
},
"403": {
"description": "The current authentication method is not an API key, or the API-key owner is not permitted to perform this operation.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiServiceError"
}
}
}
},
"404": {
"description": "Scoped access token not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiServiceError"
}
}
}
},
"500": {
"description": "Unexpected token revocation failure.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicApiServiceError"
}
}
}
}
}
}
},
"/api/ee/user": {
"get": {
"operationId": "getUser",
Expand Down
8 changes: 8 additions & 0 deletions docs/docs.json
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -189,6 +189,14 @@
"GET /api/repos"
]
},
{
"group": "Scoped Access Tokens",
"icon": "key",
"pages": [
"POST /api/ee/scoped_access_token",
"DELETE /api/ee/scoped_access_token/{id}"
]
},
{
"group": "Git",
"icon": "code-branch",
Expand Down
19 changes: 19 additions & 0 deletions docs/docs/api-reference/authentication.mdx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -32,3 +32,22 @@ curl -X POST https://your-sourcebot-instance.com/api/search \
-H "Content-Type: application/json" \
-d '{"query": "hello world", "matches": 10}'
```

## Using a scoped access token

Scoped access tokens are short-lived bearer credentials intended for clients that should only access a specific set of repositories. Create one with a Sourcebot API key by calling `POST /api/ee/scoped_access_token` with repository names:

```bash
curl -X POST https://your-sourcebot-instance.com/api/ee/scoped_access_token \
-H "Authorization: Bearer <your-api-key>" \
-H "Content-Type: application/json" \
-d '{"repos": ["github.com/acme/frontend", "github.com/acme/backend"]}'
```

The response contains an opaque token beginning with `sbst_`. It expires exactly one hour after issuance, cannot be refreshed, and is returned only once. Use it as a Bearer token with public API endpoints or the Sourcebot MCP server:

```bash
Authorization: Bearer <your-scoped-access-token>
```

Repository scope is bound internally to repository IDs and is also intersected with the creating user's current repository permissions. Creating and revoking scoped access tokens requires an API key; a scoped access token cannot mint or revoke tokens.
44 changes: 44 additions & 0 deletions packages/db/prisma/migrations/20260806033656_add_scoped_access_tokens/migration.sql
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
-- CreateTable
CREATE TABLE "ScopedAccessToken" (
"id" TEXT NOT NULL,
"hash" TEXT NOT NULL,
"createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
"expiresAt" TIMESTAMP(3) NOT NULL,
"lastUsedAt" TIMESTAMP(3),
"createdById" TEXT NOT NULL,
"orgId" INTEGER NOT NULL,

CONSTRAINT "ScopedAccessToken_pkey" PRIMARY KEY ("id")
);

-- CreateTable
CREATE TABLE "ScopedAccessTokenToRepo" (
"tokenId" TEXT NOT NULL,
"repoId" INTEGER NOT NULL,

CONSTRAINT "ScopedAccessTokenToRepo_pkey" PRIMARY KEY ("tokenId","repoId")
);

-- CreateIndex
CREATE UNIQUE INDEX "ScopedAccessToken_hash_key" ON "ScopedAccessToken"("hash");

-- CreateIndex
CREATE INDEX "ScopedAccessToken_createdById_orgId_expiresAt_idx" ON "ScopedAccessToken"("createdById", "orgId", "expiresAt");

-- CreateIndex
CREATE INDEX "ScopedAccessToken_expiresAt_idx" ON "ScopedAccessToken"("expiresAt");

-- CreateIndex
CREATE INDEX "ScopedAccessTokenToRepo_repoId_idx" ON "ScopedAccessTokenToRepo"("repoId");

-- AddForeignKey
ALTER TABLE "ScopedAccessToken" ADD CONSTRAINT "ScopedAccessToken_createdById_fkey" FOREIGN KEY ("createdById") REFERENCES "User"("id") ON DELETE CASCADE ON UPDATE CASCADE;

-- AddForeignKey
ALTER TABLE "ScopedAccessToken" ADD CONSTRAINT "ScopedAccessToken_orgId_fkey" FOREIGN KEY ("orgId") REFERENCES "Org"("id") ON DELETE CASCADE ON UPDATE CASCADE;

-- AddForeignKey
ALTER TABLE "ScopedAccessTokenToRepo" ADD CONSTRAINT "ScopedAccessTokenToRepo_tokenId_fkey" FOREIGN KEY ("tokenId") REFERENCES "ScopedAccessToken"("id") ON DELETE CASCADE ON UPDATE CASCADE;

-- AddForeignKey
ALTER TABLE "ScopedAccessTokenToRepo" ADD CONSTRAINT "ScopedAccessTokenToRepo_repoId_fkey" FOREIGN KEY ("repoId") REFERENCES "Repo"("id") ON DELETE CASCADE ON UPDATE CASCADE;
34 changes: 34 additions & 0 deletions packages/db/prisma/schema.prisma
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -71,6 +71,7 @@ model Repo {
defaultBranch String?

permittedAccounts AccountToRepoPermission[]
scopedAccessTokens ScopedAccessTokenToRepo[]
permissionSyncJobs RepoPermissionSyncJob[]
permissionSyncedAt DateTime? /// When the permissions were last synced successfully.

Expand DownExpand Up@@ -286,6 +287,7 @@ model Org {
connections Connection[]
repos Repo[]
apiKeys ApiKey[]
scopedAccessTokens ScopedAccessToken[]
scimTokens ScimToken[]
attachments Attachment[]
isOnboarded Boolean @default(false)
Expand DownExpand Up@@ -454,6 +456,37 @@ model ApiKey {
createdById String
}

model ScopedAccessToken {
id String @id @default(cuid())
hash String @unique

createdAt DateTime @default(now())
expiresAt DateTime
lastUsedAt DateTime?

createdBy User @relation(fields: [createdById], references: [id], onDelete: Cascade)
createdById String

org Org @relation(fields: [orgId], references: [id], onDelete: Cascade)
orgId Int

repos ScopedAccessTokenToRepo[]

@@index([createdById, orgId, expiresAt])
@@index([expiresAt])
}

model ScopedAccessTokenToRepo {
token ScopedAccessToken @relation(fields: [tokenId], references: [id], onDelete: Cascade)
tokenId String

repo Repo @relation(fields: [repoId], references: [id], onDelete: Cascade)
repoId Int

@@id([tokenId, repoId])
@@index([repoId])
}

/// Org-scoped bearer token presented by an IdP (Okta, Entra) to authenticate
/// against the SCIM provisioning endpoints. Unlike `ApiKey`, a SCIM token is
/// not tied to a user — it acts on behalf of the SCIM integration for the
Expand DownExpand Up@@ -509,6 +542,7 @@ model User {
invites Invite[]

apiKeys ApiKey[]
scopedAccessTokens ScopedAccessToken[]

chats Chat[]
sharedChats ChatAccess[]
Expand Down
Loading
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
feat: add repository scoped tokens#1549

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

brendan-kellam
merged 6 commits into

from

Aug 13, 2026
 Merged


feat: add repository scoped tokens
#1549
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


6 commits


Select commit
Hold shift + click to select a range
cda8c1b

feat: add repository-scoped access tokens


brendan-kellam Aug 6, 2026
2d6c321

chore: add changelog entry for scoped access tokens


brendan-kellam Aug 6, 2026
e0b2171

Merge branch 'main' into sou-1870-scoped-access-tokens


brendan-kellam Aug 6, 2026
cdc2996

feat: scope access tokens by repository ID


brendan-kellam Aug 6, 2026
c9b3cbd

feat: gate scoped access tokens by entitlement


brendan-kellam Aug 6, 2026
e16eee2

Merge remote-tracking branch 'origin/main' into sou-1870-scoped-acces…


brendan-kellam Aug 13, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


1 change: 1 addition & 0 deletions
CHANGELOG.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Added a manually triggered cloud image release workflow for isolated internal deployments. [#1566](https://github.com/sourcebot-dev/sourcebot/pull/1566)
- Added Prometheus metrics for the web process, served on `WEB_METRICS_PORT` (default `3070`). [#1570](https://github.com/sourcebot-dev/sourcebot/pull/1570)
- Added an `http_request_duration_seconds` metric recording web request latency by route, method, and status. [#1571](https://github.com/sourcebot-dev/sourcebot/pull/1571)
- [EE] Added one-hour repository-scoped access tokens with public mint and revoke APIs. [#1549](https://github.com/sourcebot-dev/sourcebot/pull/1549)

### Fixed
- Fixed the web process being capped at a ~4GiB heap regardless of how much memory the container has, which caused multi-second garbage collection pauses on larger deployments. [#1569](https://github.com/sourcebot-dev/sourcebot/pull/1569)
Expand Down

218 changes: 217 additions & 1 deletion
docs/api-reference/sourcebot-public.openapi.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -18,6 +18,10 @@
 "name": "Git",
 "description": "Git history, diff, and file content endpoints."
 },
 {
 "name": "Scoped Access Tokens",
 "description": "Mint and revoke short-lived credentials restricted to specific repositories."
 },
 {
 "name": "System",
 "description": "System health and version endpoints."
Expand DownExpand Up@@ -1090,6 +1094,63 @@
 "$ref": "#/components/schemas/PublicCommitAuthor"
 }
 },
 "PublicCreateScopedAccessTokenResponse": {
 "type": "object",
 "properties": {
 "id": {
 "type": "string",
 "description": "Identifier used to revoke the token."
 },
 "token": {
 "type": "string",
 "pattern": "^sbst_",
 "description": "Opaque bearer token. This value is returned only when the token is created."
 },
 "createdAt": {
 "type": "string",
 "format": "date-time"
 },
 "expiresAt": {
 "type": "string",
 "format": "date-time"
 },
 "repoIds": {
 "type": "array",
 "items": {
 "type": "integer",
 "minimum": 0,
 "exclusiveMinimum": true
 },
 "minItems": 1
 }
 },
 "required": [
 "id",
 "token",
 "createdAt",
 "expiresAt",
 "repoIds"
 ]
 },
 "PublicCreateScopedAccessTokenRequest": {
 "type": "object",
 "properties": {
 "repoIds": {
 "type": "array",
 "items": {
 "type": "integer",
 "minimum": 0,
 "exclusiveMinimum": true
 },
 "minItems": 1,
 "description": "Repository IDs to bind to the token. Every ID must identify a repository accessible to the API-key owner."
 }
 },
 "required": [
 "repoIds"
 ],
 "additionalProperties": false
 },
 "PublicEeUser": {
 "type": "object",
 "properties": {
Expand DownExpand Up@@ -1253,7 +1314,7 @@
 "bearerToken": {
 "type": "http",
 "scheme": "bearer",
 "description": "Bearer authentication header of the form `Bearer <token>`, where `<token>` is your API key."
 "description": "Bearer authentication header of the form `Bearer <token>`. The token may be a Sourcebot API key, OAuth access token, or scoped access token, subject to endpoint requirements."
 },
 "apiKeyHeader": {
 "type": "apiKey",
Expand DownExpand Up@@ -2266,6 +2327,161 @@
 }
 }
 },
 "/api/ee/scoped_access_token": {
 "post": {
 "operationId": "createScopedAccessToken",
 "tags": [
 "Scoped Access Tokens"
 ],
 "summary": "Create a scoped access token",
 "description": "Creates an opaque bearer token that expires exactly one hour after issuance and is restricted to the requested repositories. Repository IDs are validated atomically against the API-key owner's current access; the request fails if any ID is missing or inaccessible. Repository IDs are returned by GET /api/repos.\n\nThis endpoint requires a Sourcebot API key. Scoped access tokens, OAuth tokens, and browser sessions cannot mint another scoped access token. The returned token is independent of the API key after issuance and cannot be refreshed.",
 "security": [
 {
 "bearerToken": []
 },
 {
 "apiKeyHeader": []
 }
 ],
 "requestBody": {
 "required": true,
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicCreateScopedAccessTokenRequest"
 }
 }
 }
 },
 "responses": {
 "201": {
 "description": "Scoped access token created. The opaque token value is returned only in this response.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicCreateScopedAccessTokenResponse"
 }
 }
 }
 },
 "400": {
 "description": "Invalid request body or repository scope.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "401": {
 "description": "Missing or invalid authentication.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "403": {
 "description": "The current authentication method is not an API key, or the API-key owner is not permitted to perform this operation.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "500": {
 "description": "Unexpected token creation failure.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 }
 }
 }
 },
 "/api/ee/scoped_access_token/{id}": {
 "delete": {
 "operationId": "revokeScopedAccessToken",
 "tags": [
 "Scoped Access Tokens"
 ],
 "summary": "Revoke a scoped access token",
 "description": "Immediately revokes a scoped access token created by the authenticated API-key owner. This endpoint requires a Sourcebot API key.",
 "security": [
 {
 "bearerToken": []
 },
 {
 "apiKeyHeader": []
 }
 ],
 "parameters": [
 {
 "schema": {
 "type": "string",
 "description": "Identifier returned when the scoped access token was created."
 },
 "required": true,
 "description": "Identifier returned when the scoped access token was created.",
 "name": "id",
 "in": "path"
 }
 ],
 "responses": {
 "204": {
 "description": "Scoped access token revoked."
 },
 "401": {
 "description": "Missing or invalid authentication.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "403": {
 "description": "The current authentication method is not an API key, or the API-key owner is not permitted to perform this operation.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "404": {
 "description": "Scoped access token not found.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "500": {
 "description": "Unexpected token revocation failure.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 }
 }
 }
 },
 "/api/ee/user": {
 "get": {
 "operationId": "getUser",
Expand Down

8 changes: 8 additions & 0 deletions
docs/docs.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -189,6 +189,14 @@
 "GET /api/repos"
 ]
 },
 {
 "group": "Scoped Access Tokens",
 "icon": "key",
 "pages": [
 "POST /api/ee/scoped_access_token",
 "DELETE /api/ee/scoped_access_token/{id}"
 ]
 },
 {
 "group": "Git",
 "icon": "code-branch",
Expand Down

19 changes: 19 additions & 0 deletions
docs/docs/api-reference/authentication.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -32,3 +32,22 @@ curl -X POST https://your-sourcebot-instance.com/api/search \
 -H "Content-Type: application/json" \
 -d '{"query": "hello world", "matches": 10}'
```

## Using a scoped access token

Scoped access tokens are short-lived bearer credentials intended for clients that should only access a specific set of repositories. Create one with a Sourcebot API key by calling `POST /api/ee/scoped_access_token` with repository names:

```bash
curl -X POST https://your-sourcebot-instance.com/api/ee/scoped_access_token \
 -H "Authorization: Bearer <your-api-key>" \
 -H "Content-Type: application/json" \
 -d '{"repos": ["github.com/acme/frontend", "github.com/acme/backend"]}'
```

The response contains an opaque token beginning with `sbst_`. It expires exactly one hour after issuance, cannot be refreshed, and is returned only once. Use it as a Bearer token with public API endpoints or the Sourcebot MCP server:

```bash
Authorization: Bearer <your-scoped-access-token>
```

Repository scope is bound internally to repository IDs and is also intersected with the creating user's current repository permissions. Creating and revoking scoped access tokens requires an API key; a scoped access token cannot mint or revoke tokens.

44 changes: 44 additions & 0 deletions
packages/db/prisma/migrations/20260806033656_add_scoped_access_tokens/migration.sql

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
-- CreateTable
CREATE TABLE "ScopedAccessToken" (
 "id" TEXT NOT NULL,
 "hash" TEXT NOT NULL,
 "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
 "expiresAt" TIMESTAMP(3) NOT NULL,
 "lastUsedAt" TIMESTAMP(3),
 "createdById" TEXT NOT NULL,
 "orgId" INTEGER NOT NULL,

 CONSTRAINT "ScopedAccessToken_pkey" PRIMARY KEY ("id")
);

-- CreateTable
CREATE TABLE "ScopedAccessTokenToRepo" (
 "tokenId" TEXT NOT NULL,
 "repoId" INTEGER NOT NULL,

 CONSTRAINT "ScopedAccessTokenToRepo_pkey" PRIMARY KEY ("tokenId","repoId")
);

-- CreateIndex
CREATE UNIQUE INDEX "ScopedAccessToken_hash_key" ON "ScopedAccessToken"("hash");

-- CreateIndex
CREATE INDEX "ScopedAccessToken_createdById_orgId_expiresAt_idx" ON "ScopedAccessToken"("createdById", "orgId", "expiresAt");

-- CreateIndex
CREATE INDEX "ScopedAccessToken_expiresAt_idx" ON "ScopedAccessToken"("expiresAt");

-- CreateIndex
CREATE INDEX "ScopedAccessTokenToRepo_repoId_idx" ON "ScopedAccessTokenToRepo"("repoId");

-- AddForeignKey
ALTER TABLE "ScopedAccessToken" ADD CONSTRAINT "ScopedAccessToken_createdById_fkey" FOREIGN KEY ("createdById") REFERENCES "User"("id") ON DELETE CASCADE ON UPDATE CASCADE;

-- AddForeignKey
ALTER TABLE "ScopedAccessToken" ADD CONSTRAINT "ScopedAccessToken_orgId_fkey" FOREIGN KEY ("orgId") REFERENCES "Org"("id") ON DELETE CASCADE ON UPDATE CASCADE;

-- AddForeignKey
ALTER TABLE "ScopedAccessTokenToRepo" ADD CONSTRAINT "ScopedAccessTokenToRepo_tokenId_fkey" FOREIGN KEY ("tokenId") REFERENCES "ScopedAccessToken"("id") ON DELETE CASCADE ON UPDATE CASCADE;

-- AddForeignKey
ALTER TABLE "ScopedAccessTokenToRepo" ADD CONSTRAINT "ScopedAccessTokenToRepo_repoId_fkey" FOREIGN KEY ("repoId") REFERENCES "Repo"("id") ON DELETE CASCADE ON UPDATE CASCADE;

34 changes: 34 additions & 0 deletions
packages/db/prisma/schema.prisma

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -71,6 +71,7 @@ model Repo {
 defaultBranch String?

 permittedAccounts AccountToRepoPermission[]
 scopedAccessTokens ScopedAccessTokenToRepo[]
 permissionSyncJobs RepoPermissionSyncJob[]
 permissionSyncedAt DateTime? /// When the permissions were last synced successfully.

Expand DownExpand Up@@ -286,6 +287,7 @@ model Org {
 connections Connection[]
 repos Repo[]
 apiKeys ApiKey[]
 scopedAccessTokens ScopedAccessToken[]
 scimTokens ScimToken[]
 attachments Attachment[]
 isOnboarded Boolean @default(false)
Expand DownExpand Up@@ -454,6 +456,37 @@ model ApiKey {
 createdById String
}

model ScopedAccessToken {
 id String @id @default(cuid())
 hash String @unique

 createdAt DateTime @default(now())
 expiresAt DateTime
 lastUsedAt DateTime?

 createdBy User @relation(fields: [createdById], references: [id], onDelete: Cascade)
 createdById String

 org Org @relation(fields: [orgId], references: [id], onDelete: Cascade)
 orgId Int

 repos ScopedAccessTokenToRepo[]

 @@index([createdById, orgId, expiresAt])
 @@index([expiresAt])
}

model ScopedAccessTokenToRepo {
 token ScopedAccessToken @relation(fields: [tokenId], references: [id], onDelete: Cascade)
 tokenId String

 repo Repo @relation(fields: [repoId], references: [id], onDelete: Cascade)
 repoId Int

 @@id([tokenId, repoId])
 @@index([repoId])
}

/// Org-scoped bearer token presented by an IdP (Okta, Entra) to authenticate
/// against the SCIM provisioning endpoints. Unlike `ApiKey`, a SCIM token is
/// not tied to a user — it acts on behalf of the SCIM integration for the
Expand DownExpand Up@@ -509,6 +542,7 @@ model User {
 invites Invite[]

 apiKeys ApiKey[]
 scopedAccessTokens ScopedAccessToken[]

 chats Chat[]
 sharedChats ChatAccess[]
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
feat: add repository scoped tokens#1549

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

brendan-kellam
merged 6 commits into

from

Aug 13, 2026
 Merged


feat: add repository scoped tokens
#1549
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


6 commits


Select commit
Hold shift + click to select a range
cda8c1b

feat: add repository-scoped access tokens


brendan-kellam Aug 6, 2026
2d6c321

chore: add changelog entry for scoped access tokens


brendan-kellam Aug 6, 2026
e0b2171

Merge branch 'main' into sou-1870-scoped-access-tokens


brendan-kellam Aug 6, 2026
cdc2996

feat: scope access tokens by repository ID


brendan-kellam Aug 6, 2026
c9b3cbd

feat: gate scoped access tokens by entitlement


brendan-kellam Aug 6, 2026
e16eee2

Merge remote-tracking branch 'origin/main' into sou-1870-scoped-acces…


brendan-kellam Aug 13, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


1 change: 1 addition & 0 deletions
CHANGELOG.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Added a manually triggered cloud image release workflow for isolated internal deployments. [#1566](https://github.com/sourcebot-dev/sourcebot/pull/1566)
- Added Prometheus metrics for the web process, served on `WEB_METRICS_PORT` (default `3070`). [#1570](https://github.com/sourcebot-dev/sourcebot/pull/1570)
- Added an `http_request_duration_seconds` metric recording web request latency by route, method, and status. [#1571](https://github.com/sourcebot-dev/sourcebot/pull/1571)
- [EE] Added one-hour repository-scoped access tokens with public mint and revoke APIs. [#1549](https://github.com/sourcebot-dev/sourcebot/pull/1549)

### Fixed
- Fixed the web process being capped at a ~4GiB heap regardless of how much memory the container has, which caused multi-second garbage collection pauses on larger deployments. [#1569](https://github.com/sourcebot-dev/sourcebot/pull/1569)
Expand Down

218 changes: 217 additions & 1 deletion
docs/api-reference/sourcebot-public.openapi.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -18,6 +18,10 @@
 "name": "Git",
 "description": "Git history, diff, and file content endpoints."
 },
 {
 "name": "Scoped Access Tokens",
 "description": "Mint and revoke short-lived credentials restricted to specific repositories."
 },
 {
 "name": "System",
 "description": "System health and version endpoints."
Expand DownExpand Up@@ -1090,6 +1094,63 @@
 "$ref": "#/components/schemas/PublicCommitAuthor"
 }
 },
 "PublicCreateScopedAccessTokenResponse": {
 "type": "object",
 "properties": {
 "id": {
 "type": "string",
 "description": "Identifier used to revoke the token."
 },
 "token": {
 "type": "string",
 "pattern": "^sbst_",
 "description": "Opaque bearer token. This value is returned only when the token is created."
 },
 "createdAt": {
 "type": "string",
 "format": "date-time"
 },
 "expiresAt": {
 "type": "string",
 "format": "date-time"
 },
 "repoIds": {
 "type": "array",
 "items": {
 "type": "integer",
 "minimum": 0,
 "exclusiveMinimum": true
 },
 "minItems": 1
 }
 },
 "required": [
 "id",
 "token",
 "createdAt",
 "expiresAt",
 "repoIds"
 ]
 },
 "PublicCreateScopedAccessTokenRequest": {
 "type": "object",
 "properties": {
 "repoIds": {
 "type": "array",
 "items": {
 "type": "integer",
 "minimum": 0,
 "exclusiveMinimum": true
 },
 "minItems": 1,
 "description": "Repository IDs to bind to the token. Every ID must identify a repository accessible to the API-key owner."
 }
 },
 "required": [
 "repoIds"
 ],
 "additionalProperties": false
 },
 "PublicEeUser": {
 "type": "object",
 "properties": {
Expand DownExpand Up@@ -1253,7 +1314,7 @@
 "bearerToken": {
 "type": "http",
 "scheme": "bearer",
 "description": "Bearer authentication header of the form `Bearer <token>`, where `<token>` is your API key."
 "description": "Bearer authentication header of the form `Bearer <token>`. The token may be a Sourcebot API key, OAuth access token, or scoped access token, subject to endpoint requirements."
 },
 "apiKeyHeader": {
 "type": "apiKey",
Expand DownExpand Up@@ -2266,6 +2327,161 @@
 }
 }
 },
 "/api/ee/scoped_access_token": {
 "post": {
 "operationId": "createScopedAccessToken",
 "tags": [
 "Scoped Access Tokens"
 ],
 "summary": "Create a scoped access token",
 "description": "Creates an opaque bearer token that expires exactly one hour after issuance and is restricted to the requested repositories. Repository IDs are validated atomically against the API-key owner's current access; the request fails if any ID is missing or inaccessible. Repository IDs are returned by GET /api/repos.\n\nThis endpoint requires a Sourcebot API key. Scoped access tokens, OAuth tokens, and browser sessions cannot mint another scoped access token. The returned token is independent of the API key after issuance and cannot be refreshed.",
 "security": [
 {
 "bearerToken": []
 },
 {
 "apiKeyHeader": []
 }
 ],
 "requestBody": {
 "required": true,
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicCreateScopedAccessTokenRequest"
 }
 }
 }
 },
 "responses": {
 "201": {
 "description": "Scoped access token created. The opaque token value is returned only in this response.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicCreateScopedAccessTokenResponse"
 }
 }
 }
 },
 "400": {
 "description": "Invalid request body or repository scope.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "401": {
 "description": "Missing or invalid authentication.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "403": {
 "description": "The current authentication method is not an API key, or the API-key owner is not permitted to perform this operation.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "500": {
 "description": "Unexpected token creation failure.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 }
 }
 }
 },
 "/api/ee/scoped_access_token/{id}": {
 "delete": {
 "operationId": "revokeScopedAccessToken",
 "tags": [
 "Scoped Access Tokens"
 ],
 "summary": "Revoke a scoped access token",
 "description": "Immediately revokes a scoped access token created by the authenticated API-key owner. This endpoint requires a Sourcebot API key.",
 "security": [
 {
 "bearerToken": []
 },
 {
 "apiKeyHeader": []
 }
 ],
 "parameters": [
 {
 "schema": {
 "type": "string",
 "description": "Identifier returned when the scoped access token was created."
 },
 "required": true,
 "description": "Identifier returned when the scoped access token was created.",
 "name": "id",
 "in": "path"
 }
 ],
 "responses": {
 "204": {
 "description": "Scoped access token revoked."
 },
 "401": {
 "description": "Missing or invalid authentication.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "403": {
 "description": "The current authentication method is not an API key, or the API-key owner is not permitted to perform this operation.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "404": {
 "description": "Scoped access token not found.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "500": {
 "description": "Unexpected token revocation failure.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 }
 }
 }
 },
 "/api/ee/user": {
 "get": {
 "operationId": "getUser",
Expand Down

8 changes: 8 additions & 0 deletions
docs/docs.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -189,6 +189,14 @@
 "GET /api/repos"
 ]
 },
 {
 "group": "Scoped Access Tokens",
 "icon": "key",
 "pages": [
 "POST /api/ee/scoped_access_token",
 "DELETE /api/ee/scoped_access_token/{id}"
 ]
 },
 {
 "group": "Git",
 "icon": "code-branch",
Expand Down

19 changes: 19 additions & 0 deletions
docs/docs/api-reference/authentication.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -32,3 +32,22 @@ curl -X POST https://your-sourcebot-instance.com/api/search \
 -H "Content-Type: application/json" \
 -d '{"query": "hello world", "matches": 10}'
```

## Using a scoped access token

Scoped access tokens are short-lived bearer credentials intended for clients that should only access a specific set of repositories. Create one with a Sourcebot API key by calling `POST /api/ee/scoped_access_token` with repository names:

```bash
curl -X POST https://your-sourcebot-instance.com/api/ee/scoped_access_token \
 -H "Authorization: Bearer <your-api-key>" \
 -H "Content-Type: application/json" \
 -d '{"repos": ["github.com/acme/frontend", "github.com/acme/backend"]}'
```

The response contains an opaque token beginning with `sbst_`. It expires exactly one hour after issuance, cannot be refreshed, and is returned only once. Use it as a Bearer token with public API endpoints or the Sourcebot MCP server:

```bash
Authorization: Bearer <your-scoped-access-token>
```

Repository scope is bound internally to repository IDs and is also intersected with the creating user's current repository permissions. Creating and revoking scoped access tokens requires an API key; a scoped access token cannot mint or revoke tokens.

44 changes: 44 additions & 0 deletions
packages/db/prisma/migrations/20260806033656_add_scoped_access_tokens/migration.sql

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
-- CreateTable
CREATE TABLE "ScopedAccessToken" (
 "id" TEXT NOT NULL,
 "hash" TEXT NOT NULL,
 "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
 "expiresAt" TIMESTAMP(3) NOT NULL,
 "lastUsedAt" TIMESTAMP(3),
 "createdById" TEXT NOT NULL,
 "orgId" INTEGER NOT NULL,

 CONSTRAINT "ScopedAccessToken_pkey" PRIMARY KEY ("id")
);

-- CreateTable
CREATE TABLE "ScopedAccessTokenToRepo" (
 "tokenId" TEXT NOT NULL,
 "repoId" INTEGER NOT NULL,

 CONSTRAINT "ScopedAccessTokenToRepo_pkey" PRIMARY KEY ("tokenId","repoId")
);

-- CreateIndex
CREATE UNIQUE INDEX "ScopedAccessToken_hash_key" ON "ScopedAccessToken"("hash");

-- CreateIndex
CREATE INDEX "ScopedAccessToken_createdById_orgId_expiresAt_idx" ON "ScopedAccessToken"("createdById", "orgId", "expiresAt");

-- CreateIndex
CREATE INDEX "ScopedAccessToken_expiresAt_idx" ON "ScopedAccessToken"("expiresAt");

-- CreateIndex
CREATE INDEX "ScopedAccessTokenToRepo_repoId_idx" ON "ScopedAccessTokenToRepo"("repoId");

-- AddForeignKey
ALTER TABLE "ScopedAccessToken" ADD CONSTRAINT "ScopedAccessToken_createdById_fkey" FOREIGN KEY ("createdById") REFERENCES "User"("id") ON DELETE CASCADE ON UPDATE CASCADE;

-- AddForeignKey
ALTER TABLE "ScopedAccessToken" ADD CONSTRAINT "ScopedAccessToken_orgId_fkey" FOREIGN KEY ("orgId") REFERENCES "Org"("id") ON DELETE CASCADE ON UPDATE CASCADE;

-- AddForeignKey
ALTER TABLE "ScopedAccessTokenToRepo" ADD CONSTRAINT "ScopedAccessTokenToRepo_tokenId_fkey" FOREIGN KEY ("tokenId") REFERENCES "ScopedAccessToken"("id") ON DELETE CASCADE ON UPDATE CASCADE;

-- AddForeignKey
ALTER TABLE "ScopedAccessTokenToRepo" ADD CONSTRAINT "ScopedAccessTokenToRepo_repoId_fkey" FOREIGN KEY ("repoId") REFERENCES "Repo"("id") ON DELETE CASCADE ON UPDATE CASCADE;

34 changes: 34 additions & 0 deletions
packages/db/prisma/schema.prisma

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -71,6 +71,7 @@ model Repo {
 defaultBranch String?

 permittedAccounts AccountToRepoPermission[]
 scopedAccessTokens ScopedAccessTokenToRepo[]
 permissionSyncJobs RepoPermissionSyncJob[]
 permissionSyncedAt DateTime? /// When the permissions were last synced successfully.

Expand DownExpand Up@@ -286,6 +287,7 @@ model Org {
 connections Connection[]
 repos Repo[]
 apiKeys ApiKey[]
 scopedAccessTokens ScopedAccessToken[]
 scimTokens ScimToken[]
 attachments Attachment[]
 isOnboarded Boolean @default(false)
Expand DownExpand Up@@ -454,6 +456,37 @@ model ApiKey {
 createdById String
}

model ScopedAccessToken {
 id String @id @default(cuid())
 hash String @unique

 createdAt DateTime @default(now())
 expiresAt DateTime
 lastUsedAt DateTime?

 createdBy User @relation(fields: [createdById], references: [id], onDelete: Cascade)
 createdById String

 org Org @relation(fields: [orgId], references: [id], onDelete: Cascade)
 orgId Int

 repos ScopedAccessTokenToRepo[]

 @@index([createdById, orgId, expiresAt])
 @@index([expiresAt])
}

model ScopedAccessTokenToRepo {
 token ScopedAccessToken @relation(fields: [tokenId], references: [id], onDelete: Cascade)
 tokenId String

 repo Repo @relation(fields: [repoId], references: [id], onDelete: Cascade)
 repoId Int

 @@id([tokenId, repoId])
 @@index([repoId])
}

/// Org-scoped bearer token presented by an IdP (Okta, Entra) to authenticate
/// against the SCIM provisioning endpoints. Unlike `ApiKey`, a SCIM token is
/// not tied to a user — it acts on behalf of the SCIM integration for the
Expand DownExpand Up@@ -509,6 +542,7 @@ model User {
 invites Invite[]

 apiKeys ApiKey[]
 scopedAccessTokens ScopedAccessToken[]

 chats Chat[]
 sharedChats ChatAccess[]
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
feat: add repository scoped tokens#1549

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

brendan-kellam
merged 6 commits into

from

Aug 13, 2026
 Merged


feat: add repository scoped tokens
#1549
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


6 commits


Select commit
Hold shift + click to select a range
cda8c1b

feat: add repository-scoped access tokens


brendan-kellam Aug 6, 2026
2d6c321

chore: add changelog entry for scoped access tokens


brendan-kellam Aug 6, 2026
e0b2171

Merge branch 'main' into sou-1870-scoped-access-tokens


brendan-kellam Aug 6, 2026
cdc2996

feat: scope access tokens by repository ID


brendan-kellam Aug 6, 2026
c9b3cbd

feat: gate scoped access tokens by entitlement


brendan-kellam Aug 6, 2026
e16eee2

Merge remote-tracking branch 'origin/main' into sou-1870-scoped-acces…


brendan-kellam Aug 13, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


1 change: 1 addition & 0 deletions
CHANGELOG.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Added a manually triggered cloud image release workflow for isolated internal deployments. [#1566](https://github.com/sourcebot-dev/sourcebot/pull/1566)
- Added Prometheus metrics for the web process, served on `WEB_METRICS_PORT` (default `3070`). [#1570](https://github.com/sourcebot-dev/sourcebot/pull/1570)
- Added an `http_request_duration_seconds` metric recording web request latency by route, method, and status. [#1571](https://github.com/sourcebot-dev/sourcebot/pull/1571)
- [EE] Added one-hour repository-scoped access tokens with public mint and revoke APIs. [#1549](https://github.com/sourcebot-dev/sourcebot/pull/1549)

### Fixed
- Fixed the web process being capped at a ~4GiB heap regardless of how much memory the container has, which caused multi-second garbage collection pauses on larger deployments. [#1569](https://github.com/sourcebot-dev/sourcebot/pull/1569)
Expand Down

218 changes: 217 additions & 1 deletion
docs/api-reference/sourcebot-public.openapi.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -18,6 +18,10 @@
 "name": "Git",
 "description": "Git history, diff, and file content endpoints."
 },
 {
 "name": "Scoped Access Tokens",
 "description": "Mint and revoke short-lived credentials restricted to specific repositories."
 },
 {
 "name": "System",
 "description": "System health and version endpoints."
Expand DownExpand Up@@ -1090,6 +1094,63 @@
 "$ref": "#/components/schemas/PublicCommitAuthor"
 }
 },
 "PublicCreateScopedAccessTokenResponse": {
 "type": "object",
 "properties": {
 "id": {
 "type": "string",
 "description": "Identifier used to revoke the token."
 },
 "token": {
 "type": "string",
 "pattern": "^sbst_",
 "description": "Opaque bearer token. This value is returned only when the token is created."
 },
 "createdAt": {
 "type": "string",
 "format": "date-time"
 },
 "expiresAt": {
 "type": "string",
 "format": "date-time"
 },
 "repoIds": {
 "type": "array",
 "items": {
 "type": "integer",
 "minimum": 0,
 "exclusiveMinimum": true
 },
 "minItems": 1
 }
 },
 "required": [
 "id",
 "token",
 "createdAt",
 "expiresAt",
 "repoIds"
 ]
 },
 "PublicCreateScopedAccessTokenRequest": {
 "type": "object",
 "properties": {
 "repoIds": {
 "type": "array",
 "items": {
 "type": "integer",
 "minimum": 0,
 "exclusiveMinimum": true
 },
 "minItems": 1,
 "description": "Repository IDs to bind to the token. Every ID must identify a repository accessible to the API-key owner."
 }
 },
 "required": [
 "repoIds"
 ],
 "additionalProperties": false
 },
 "PublicEeUser": {
 "type": "object",
 "properties": {
Expand DownExpand Up@@ -1253,7 +1314,7 @@
 "bearerToken": {
 "type": "http",
 "scheme": "bearer",
 "description": "Bearer authentication header of the form `Bearer <token>`, where `<token>` is your API key."
 "description": "Bearer authentication header of the form `Bearer <token>`. The token may be a Sourcebot API key, OAuth access token, or scoped access token, subject to endpoint requirements."
 },
 "apiKeyHeader": {
 "type": "apiKey",
Expand DownExpand Up@@ -2266,6 +2327,161 @@
 }
 }
 },
 "/api/ee/scoped_access_token": {
 "post": {
 "operationId": "createScopedAccessToken",
 "tags": [
 "Scoped Access Tokens"
 ],
 "summary": "Create a scoped access token",
 "description": "Creates an opaque bearer token that expires exactly one hour after issuance and is restricted to the requested repositories. Repository IDs are validated atomically against the API-key owner's current access; the request fails if any ID is missing or inaccessible. Repository IDs are returned by GET /api/repos.\n\nThis endpoint requires a Sourcebot API key. Scoped access tokens, OAuth tokens, and browser sessions cannot mint another scoped access token. The returned token is independent of the API key after issuance and cannot be refreshed.",
 "security": [
 {
 "bearerToken": []
 },
 {
 "apiKeyHeader": []
 }
 ],
 "requestBody": {
 "required": true,
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicCreateScopedAccessTokenRequest"
 }
 }
 }
 },
 "responses": {
 "201": {
 "description": "Scoped access token created. The opaque token value is returned only in this response.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicCreateScopedAccessTokenResponse"
 }
 }
 }
 },
 "400": {
 "description": "Invalid request body or repository scope.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "401": {
 "description": "Missing or invalid authentication.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "403": {
 "description": "The current authentication method is not an API key, or the API-key owner is not permitted to perform this operation.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "500": {
 "description": "Unexpected token creation failure.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 }
 }
 }
 },
 "/api/ee/scoped_access_token/{id}": {
 "delete": {
 "operationId": "revokeScopedAccessToken",
 "tags": [
 "Scoped Access Tokens"
 ],
 "summary": "Revoke a scoped access token",
 "description": "Immediately revokes a scoped access token created by the authenticated API-key owner. This endpoint requires a Sourcebot API key.",
 "security": [
 {
 "bearerToken": []
 },
 {
 "apiKeyHeader": []
 }
 ],
 "parameters": [
 {
 "schema": {
 "type": "string",
 "description": "Identifier returned when the scoped access token was created."
 },
 "required": true,
 "description": "Identifier returned when the scoped access token was created.",
 "name": "id",
 "in": "path"
 }
 ],
 "responses": {
 "204": {
 "description": "Scoped access token revoked."
 },
 "401": {
 "description": "Missing or invalid authentication.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "403": {
 "description": "The current authentication method is not an API key, or the API-key owner is not permitted to perform this operation.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "404": {
 "description": "Scoped access token not found.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "500": {
 "description": "Unexpected token revocation failure.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 }
 }
 }
 },
 "/api/ee/user": {
 "get": {
 "operationId": "getUser",
Expand Down

8 changes: 8 additions & 0 deletions
docs/docs.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -189,6 +189,14 @@
 "GET /api/repos"
 ]
 },
 {
 "group": "Scoped Access Tokens",
 "icon": "key",
 "pages": [
 "POST /api/ee/scoped_access_token",
 "DELETE /api/ee/scoped_access_token/{id}"
 ]
 },
 {
 "group": "Git",
 "icon": "code-branch",
Expand Down

19 changes: 19 additions & 0 deletions
docs/docs/api-reference/authentication.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -32,3 +32,22 @@ curl -X POST https://your-sourcebot-instance.com/api/search \
 -H "Content-Type: application/json" \
 -d '{"query": "hello world", "matches": 10}'
```

## Using a scoped access token

Scoped access tokens are short-lived bearer credentials intended for clients that should only access a specific set of repositories. Create one with a Sourcebot API key by calling `POST /api/ee/scoped_access_token` with repository names:

```bash
curl -X POST https://your-sourcebot-instance.com/api/ee/scoped_access_token \
 -H "Authorization: Bearer <your-api-key>" \
 -H "Content-Type: application/json" \
 -d '{"repos": ["github.com/acme/frontend", "github.com/acme/backend"]}'
```

The response contains an opaque token beginning with `sbst_`. It expires exactly one hour after issuance, cannot be refreshed, and is returned only once. Use it as a Bearer token with public API endpoints or the Sourcebot MCP server:

```bash
Authorization: Bearer <your-scoped-access-token>
```

Repository scope is bound internally to repository IDs and is also intersected with the creating user's current repository permissions. Creating and revoking scoped access tokens requires an API key; a scoped access token cannot mint or revoke tokens.

44 changes: 44 additions & 0 deletions
packages/db/prisma/migrations/20260806033656_add_scoped_access_tokens/migration.sql

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
-- CreateTable
CREATE TABLE "ScopedAccessToken" (
 "id" TEXT NOT NULL,
 "hash" TEXT NOT NULL,
 "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
 "expiresAt" TIMESTAMP(3) NOT NULL,
 "lastUsedAt" TIMESTAMP(3),
 "createdById" TEXT NOT NULL,
 "orgId" INTEGER NOT NULL,

 CONSTRAINT "ScopedAccessToken_pkey" PRIMARY KEY ("id")
);

-- CreateTable
CREATE TABLE "ScopedAccessTokenToRepo" (
 "tokenId" TEXT NOT NULL,
 "repoId" INTEGER NOT NULL,

 CONSTRAINT "ScopedAccessTokenToRepo_pkey" PRIMARY KEY ("tokenId","repoId")
);

-- CreateIndex
CREATE UNIQUE INDEX "ScopedAccessToken_hash_key" ON "ScopedAccessToken"("hash");

-- CreateIndex
CREATE INDEX "ScopedAccessToken_createdById_orgId_expiresAt_idx" ON "ScopedAccessToken"("createdById", "orgId", "expiresAt");

-- CreateIndex
CREATE INDEX "ScopedAccessToken_expiresAt_idx" ON "ScopedAccessToken"("expiresAt");

-- CreateIndex
CREATE INDEX "ScopedAccessTokenToRepo_repoId_idx" ON "ScopedAccessTokenToRepo"("repoId");

-- AddForeignKey
ALTER TABLE "ScopedAccessToken" ADD CONSTRAINT "ScopedAccessToken_createdById_fkey" FOREIGN KEY ("createdById") REFERENCES "User"("id") ON DELETE CASCADE ON UPDATE CASCADE;

-- AddForeignKey
ALTER TABLE "ScopedAccessToken" ADD CONSTRAINT "ScopedAccessToken_orgId_fkey" FOREIGN KEY ("orgId") REFERENCES "Org"("id") ON DELETE CASCADE ON UPDATE CASCADE;

-- AddForeignKey
ALTER TABLE "ScopedAccessTokenToRepo" ADD CONSTRAINT "ScopedAccessTokenToRepo_tokenId_fkey" FOREIGN KEY ("tokenId") REFERENCES "ScopedAccessToken"("id") ON DELETE CASCADE ON UPDATE CASCADE;

-- AddForeignKey
ALTER TABLE "ScopedAccessTokenToRepo" ADD CONSTRAINT "ScopedAccessTokenToRepo_repoId_fkey" FOREIGN KEY ("repoId") REFERENCES "Repo"("id") ON DELETE CASCADE ON UPDATE CASCADE;

34 changes: 34 additions & 0 deletions
packages/db/prisma/schema.prisma

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -71,6 +71,7 @@ model Repo {
 defaultBranch String?

 permittedAccounts AccountToRepoPermission[]
 scopedAccessTokens ScopedAccessTokenToRepo[]
 permissionSyncJobs RepoPermissionSyncJob[]
 permissionSyncedAt DateTime? /// When the permissions were last synced successfully.

Expand DownExpand Up@@ -286,6 +287,7 @@ model Org {
 connections Connection[]
 repos Repo[]
 apiKeys ApiKey[]
 scopedAccessTokens ScopedAccessToken[]
 scimTokens ScimToken[]
 attachments Attachment[]
 isOnboarded Boolean @default(false)
Expand DownExpand Up@@ -454,6 +456,37 @@ model ApiKey {
 createdById String
}

model ScopedAccessToken {
 id String @id @default(cuid())
 hash String @unique

 createdAt DateTime @default(now())
 expiresAt DateTime
 lastUsedAt DateTime?

 createdBy User @relation(fields: [createdById], references: [id], onDelete: Cascade)
 createdById String

 org Org @relation(fields: [orgId], references: [id], onDelete: Cascade)
 orgId Int

 repos ScopedAccessTokenToRepo[]

 @@index([createdById, orgId, expiresAt])
 @@index([expiresAt])
}

model ScopedAccessTokenToRepo {
 token ScopedAccessToken @relation(fields: [tokenId], references: [id], onDelete: Cascade)
 tokenId String

 repo Repo @relation(fields: [repoId], references: [id], onDelete: Cascade)
 repoId Int

 @@id([tokenId, repoId])
 @@index([repoId])
}

/// Org-scoped bearer token presented by an IdP (Okta, Entra) to authenticate
/// against the SCIM provisioning endpoints. Unlike `ApiKey`, a SCIM token is
/// not tied to a user — it acts on behalf of the SCIM integration for the
Expand DownExpand Up@@ -509,6 +542,7 @@ model User {
 invites Invite[]

 apiKeys ApiKey[]
 scopedAccessTokens ScopedAccessToken[]

 chats Chat[]
 sharedChats ChatAccess[]
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
feat: add repository scoped tokens#1549

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

brendan-kellam
merged 6 commits into

from

Aug 13, 2026
 Merged


feat: add repository scoped tokens
#1549
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


6 commits


Select commit
Hold shift + click to select a range
cda8c1b

feat: add repository-scoped access tokens


brendan-kellam Aug 6, 2026
2d6c321

chore: add changelog entry for scoped access tokens


brendan-kellam Aug 6, 2026
e0b2171

Merge branch 'main' into sou-1870-scoped-access-tokens


brendan-kellam Aug 6, 2026
cdc2996

feat: scope access tokens by repository ID


brendan-kellam Aug 6, 2026
c9b3cbd

feat: gate scoped access tokens by entitlement


brendan-kellam Aug 6, 2026
e16eee2

Merge remote-tracking branch 'origin/main' into sou-1870-scoped-acces…


brendan-kellam Aug 13, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


1 change: 1 addition & 0 deletions
CHANGELOG.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Added a manually triggered cloud image release workflow for isolated internal deployments. [#1566](https://github.com/sourcebot-dev/sourcebot/pull/1566)
- Added Prometheus metrics for the web process, served on `WEB_METRICS_PORT` (default `3070`). [#1570](https://github.com/sourcebot-dev/sourcebot/pull/1570)
- Added an `http_request_duration_seconds` metric recording web request latency by route, method, and status. [#1571](https://github.com/sourcebot-dev/sourcebot/pull/1571)
- [EE] Added one-hour repository-scoped access tokens with public mint and revoke APIs. [#1549](https://github.com/sourcebot-dev/sourcebot/pull/1549)

### Fixed
- Fixed the web process being capped at a ~4GiB heap regardless of how much memory the container has, which caused multi-second garbage collection pauses on larger deployments. [#1569](https://github.com/sourcebot-dev/sourcebot/pull/1569)
Expand Down

218 changes: 217 additions & 1 deletion
docs/api-reference/sourcebot-public.openapi.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -18,6 +18,10 @@
 "name": "Git",
 "description": "Git history, diff, and file content endpoints."
 },
 {
 "name": "Scoped Access Tokens",
 "description": "Mint and revoke short-lived credentials restricted to specific repositories."
 },
 {
 "name": "System",
 "description": "System health and version endpoints."
Expand DownExpand Up@@ -1090,6 +1094,63 @@
 "$ref": "#/components/schemas/PublicCommitAuthor"
 }
 },
 "PublicCreateScopedAccessTokenResponse": {
 "type": "object",
 "properties": {
 "id": {
 "type": "string",
 "description": "Identifier used to revoke the token."
 },
 "token": {
 "type": "string",
 "pattern": "^sbst_",
 "description": "Opaque bearer token. This value is returned only when the token is created."
 },
 "createdAt": {
 "type": "string",
 "format": "date-time"
 },
 "expiresAt": {
 "type": "string",
 "format": "date-time"
 },
 "repoIds": {
 "type": "array",
 "items": {
 "type": "integer",
 "minimum": 0,
 "exclusiveMinimum": true
 },
 "minItems": 1
 }
 },
 "required": [
 "id",
 "token",
 "createdAt",
 "expiresAt",
 "repoIds"
 ]
 },
 "PublicCreateScopedAccessTokenRequest": {
 "type": "object",
 "properties": {
 "repoIds": {
 "type": "array",
 "items": {
 "type": "integer",
 "minimum": 0,
 "exclusiveMinimum": true
 },
 "minItems": 1,
 "description": "Repository IDs to bind to the token. Every ID must identify a repository accessible to the API-key owner."
 }
 },
 "required": [
 "repoIds"
 ],
 "additionalProperties": false
 },
 "PublicEeUser": {
 "type": "object",
 "properties": {
Expand DownExpand Up@@ -1253,7 +1314,7 @@
 "bearerToken": {
 "type": "http",
 "scheme": "bearer",
 "description": "Bearer authentication header of the form `Bearer <token>`, where `<token>` is your API key."
 "description": "Bearer authentication header of the form `Bearer <token>`. The token may be a Sourcebot API key, OAuth access token, or scoped access token, subject to endpoint requirements."
 },
 "apiKeyHeader": {
 "type": "apiKey",
Expand DownExpand Up@@ -2266,6 +2327,161 @@
 }
 }
 },
 "/api/ee/scoped_access_token": {
 "post": {
 "operationId": "createScopedAccessToken",
 "tags": [
 "Scoped Access Tokens"
 ],
 "summary": "Create a scoped access token",
 "description": "Creates an opaque bearer token that expires exactly one hour after issuance and is restricted to the requested repositories. Repository IDs are validated atomically against the API-key owner's current access; the request fails if any ID is missing or inaccessible. Repository IDs are returned by GET /api/repos.\n\nThis endpoint requires a Sourcebot API key. Scoped access tokens, OAuth tokens, and browser sessions cannot mint another scoped access token. The returned token is independent of the API key after issuance and cannot be refreshed.",
 "security": [
 {
 "bearerToken": []
 },
 {
 "apiKeyHeader": []
 }
 ],
 "requestBody": {
 "required": true,
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicCreateScopedAccessTokenRequest"
 }
 }
 }
 },
 "responses": {
 "201": {
 "description": "Scoped access token created. The opaque token value is returned only in this response.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicCreateScopedAccessTokenResponse"
 }
 }
 }
 },
 "400": {
 "description": "Invalid request body or repository scope.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "401": {
 "description": "Missing or invalid authentication.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "403": {
 "description": "The current authentication method is not an API key, or the API-key owner is not permitted to perform this operation.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "500": {
 "description": "Unexpected token creation failure.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 }
 }
 }
 },
 "/api/ee/scoped_access_token/{id}": {
 "delete": {
 "operationId": "revokeScopedAccessToken",
 "tags": [
 "Scoped Access Tokens"
 ],
 "summary": "Revoke a scoped access token",
 "description": "Immediately revokes a scoped access token created by the authenticated API-key owner. This endpoint requires a Sourcebot API key.",
 "security": [
 {
 "bearerToken": []
 },
 {
 "apiKeyHeader": []
 }
 ],
 "parameters": [
 {
 "schema": {
 "type": "string",
 "description": "Identifier returned when the scoped access token was created."
 },
 "required": true,
 "description": "Identifier returned when the scoped access token was created.",
 "name": "id",
 "in": "path"
 }
 ],
 "responses": {
 "204": {
 "description": "Scoped access token revoked."
 },
 "401": {
 "description": "Missing or invalid authentication.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "403": {
 "description": "The current authentication method is not an API key, or the API-key owner is not permitted to perform this operation.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "404": {
 "description": "Scoped access token not found.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "500": {
 "description": "Unexpected token revocation failure.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 }
 }
 }
 },
 "/api/ee/user": {
 "get": {
 "operationId": "getUser",
Expand Down

8 changes: 8 additions & 0 deletions
docs/docs.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -189,6 +189,14 @@
 "GET /api/repos"
 ]
 },
 {
 "group": "Scoped Access Tokens",
 "icon": "key",
 "pages": [
 "POST /api/ee/scoped_access_token",
 "DELETE /api/ee/scoped_access_token/{id}"
 ]
 },
 {
 "group": "Git",
 "icon": "code-branch",
Expand Down

19 changes: 19 additions & 0 deletions
docs/docs/api-reference/authentication.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -32,3 +32,22 @@ curl -X POST https://your-sourcebot-instance.com/api/search \
 -H "Content-Type: application/json" \
 -d '{"query": "hello world", "matches": 10}'
```

## Using a scoped access token

Scoped access tokens are short-lived bearer credentials intended for clients that should only access a specific set of repositories. Create one with a Sourcebot API key by calling `POST /api/ee/scoped_access_token` with repository names:

```bash
curl -X POST https://your-sourcebot-instance.com/api/ee/scoped_access_token \
 -H "Authorization: Bearer <your-api-key>" \
 -H "Content-Type: application/json" \
 -d '{"repos": ["github.com/acme/frontend", "github.com/acme/backend"]}'
```

The response contains an opaque token beginning with `sbst_`. It expires exactly one hour after issuance, cannot be refreshed, and is returned only once. Use it as a Bearer token with public API endpoints or the Sourcebot MCP server:

```bash
Authorization: Bearer <your-scoped-access-token>
```

Repository scope is bound internally to repository IDs and is also intersected with the creating user's current repository permissions. Creating and revoking scoped access tokens requires an API key; a scoped access token cannot mint or revoke tokens.

44 changes: 44 additions & 0 deletions
packages/db/prisma/migrations/20260806033656_add_scoped_access_tokens/migration.sql

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
-- CreateTable
CREATE TABLE "ScopedAccessToken" (
 "id" TEXT NOT NULL,
 "hash" TEXT NOT NULL,
 "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
 "expiresAt" TIMESTAMP(3) NOT NULL,
 "lastUsedAt" TIMESTAMP(3),
 "createdById" TEXT NOT NULL,
 "orgId" INTEGER NOT NULL,

 CONSTRAINT "ScopedAccessToken_pkey" PRIMARY KEY ("id")
);

-- CreateTable
CREATE TABLE "ScopedAccessTokenToRepo" (
 "tokenId" TEXT NOT NULL,
 "repoId" INTEGER NOT NULL,

 CONSTRAINT "ScopedAccessTokenToRepo_pkey" PRIMARY KEY ("tokenId","repoId")
);

-- CreateIndex
CREATE UNIQUE INDEX "ScopedAccessToken_hash_key" ON "ScopedAccessToken"("hash");

-- CreateIndex
CREATE INDEX "ScopedAccessToken_createdById_orgId_expiresAt_idx" ON "ScopedAccessToken"("createdById", "orgId", "expiresAt");

-- CreateIndex
CREATE INDEX "ScopedAccessToken_expiresAt_idx" ON "ScopedAccessToken"("expiresAt");

-- CreateIndex
CREATE INDEX "ScopedAccessTokenToRepo_repoId_idx" ON "ScopedAccessTokenToRepo"("repoId");

-- AddForeignKey
ALTER TABLE "ScopedAccessToken" ADD CONSTRAINT "ScopedAccessToken_createdById_fkey" FOREIGN KEY ("createdById") REFERENCES "User"("id") ON DELETE CASCADE ON UPDATE CASCADE;

-- AddForeignKey
ALTER TABLE "ScopedAccessToken" ADD CONSTRAINT "ScopedAccessToken_orgId_fkey" FOREIGN KEY ("orgId") REFERENCES "Org"("id") ON DELETE CASCADE ON UPDATE CASCADE;

-- AddForeignKey
ALTER TABLE "ScopedAccessTokenToRepo" ADD CONSTRAINT "ScopedAccessTokenToRepo_tokenId_fkey" FOREIGN KEY ("tokenId") REFERENCES "ScopedAccessToken"("id") ON DELETE CASCADE ON UPDATE CASCADE;

-- AddForeignKey
ALTER TABLE "ScopedAccessTokenToRepo" ADD CONSTRAINT "ScopedAccessTokenToRepo_repoId_fkey" FOREIGN KEY ("repoId") REFERENCES "Repo"("id") ON DELETE CASCADE ON UPDATE CASCADE;

34 changes: 34 additions & 0 deletions
packages/db/prisma/schema.prisma

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -71,6 +71,7 @@ model Repo {
 defaultBranch String?

 permittedAccounts AccountToRepoPermission[]
 scopedAccessTokens ScopedAccessTokenToRepo[]
 permissionSyncJobs RepoPermissionSyncJob[]
 permissionSyncedAt DateTime? /// When the permissions were last synced successfully.

Expand DownExpand Up@@ -286,6 +287,7 @@ model Org {
 connections Connection[]
 repos Repo[]
 apiKeys ApiKey[]
 scopedAccessTokens ScopedAccessToken[]
 scimTokens ScimToken[]
 attachments Attachment[]
 isOnboarded Boolean @default(false)
Expand DownExpand Up@@ -454,6 +456,37 @@ model ApiKey {
 createdById String
}

model ScopedAccessToken {
 id String @id @default(cuid())
 hash String @unique

 createdAt DateTime @default(now())
 expiresAt DateTime
 lastUsedAt DateTime?

 createdBy User @relation(fields: [createdById], references: [id], onDelete: Cascade)
 createdById String

 org Org @relation(fields: [orgId], references: [id], onDelete: Cascade)
 orgId Int

 repos ScopedAccessTokenToRepo[]

 @@index([createdById, orgId, expiresAt])
 @@index([expiresAt])
}

model ScopedAccessTokenToRepo {
 token ScopedAccessToken @relation(fields: [tokenId], references: [id], onDelete: Cascade)
 tokenId String

 repo Repo @relation(fields: [repoId], references: [id], onDelete: Cascade)
 repoId Int

 @@id([tokenId, repoId])
 @@index([repoId])
}

/// Org-scoped bearer token presented by an IdP (Okta, Entra) to authenticate
/// against the SCIM provisioning endpoints. Unlike `ApiKey`, a SCIM token is
/// not tied to a user — it acts on behalf of the SCIM integration for the
Expand DownExpand Up@@ -509,6 +542,7 @@ model User {
 invites Invite[]

 apiKeys ApiKey[]
 scopedAccessTokens ScopedAccessToken[]

 chats Chat[]
 sharedChats ChatAccess[]
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
feat: add repository scoped tokens#1549

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

brendan-kellam
merged 6 commits into

from

Aug 13, 2026
 Merged


feat: add repository scoped tokens
#1549
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


6 commits


Select commit
Hold shift + click to select a range
cda8c1b

feat: add repository-scoped access tokens


brendan-kellam Aug 6, 2026
2d6c321

chore: add changelog entry for scoped access tokens


brendan-kellam Aug 6, 2026
e0b2171

Merge branch 'main' into sou-1870-scoped-access-tokens


brendan-kellam Aug 6, 2026
cdc2996

feat: scope access tokens by repository ID


brendan-kellam Aug 6, 2026
c9b3cbd

feat: gate scoped access tokens by entitlement


brendan-kellam Aug 6, 2026
e16eee2

Merge remote-tracking branch 'origin/main' into sou-1870-scoped-acces…


brendan-kellam Aug 13, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


1 change: 1 addition & 0 deletions
CHANGELOG.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Added a manually triggered cloud image release workflow for isolated internal deployments. [#1566](https://github.com/sourcebot-dev/sourcebot/pull/1566)
- Added Prometheus metrics for the web process, served on `WEB_METRICS_PORT` (default `3070`). [#1570](https://github.com/sourcebot-dev/sourcebot/pull/1570)
- Added an `http_request_duration_seconds` metric recording web request latency by route, method, and status. [#1571](https://github.com/sourcebot-dev/sourcebot/pull/1571)
- [EE] Added one-hour repository-scoped access tokens with public mint and revoke APIs. [#1549](https://github.com/sourcebot-dev/sourcebot/pull/1549)

### Fixed
- Fixed the web process being capped at a ~4GiB heap regardless of how much memory the container has, which caused multi-second garbage collection pauses on larger deployments. [#1569](https://github.com/sourcebot-dev/sourcebot/pull/1569)
Expand Down

218 changes: 217 additions & 1 deletion
docs/api-reference/sourcebot-public.openapi.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -18,6 +18,10 @@
 "name": "Git",
 "description": "Git history, diff, and file content endpoints."
 },
 {
 "name": "Scoped Access Tokens",
 "description": "Mint and revoke short-lived credentials restricted to specific repositories."
 },
 {
 "name": "System",
 "description": "System health and version endpoints."
Expand DownExpand Up@@ -1090,6 +1094,63 @@
 "$ref": "#/components/schemas/PublicCommitAuthor"
 }
 },
 "PublicCreateScopedAccessTokenResponse": {
 "type": "object",
 "properties": {
 "id": {
 "type": "string",
 "description": "Identifier used to revoke the token."
 },
 "token": {
 "type": "string",
 "pattern": "^sbst_",
 "description": "Opaque bearer token. This value is returned only when the token is created."
 },
 "createdAt": {
 "type": "string",
 "format": "date-time"
 },
 "expiresAt": {
 "type": "string",
 "format": "date-time"
 },
 "repoIds": {
 "type": "array",
 "items": {
 "type": "integer",
 "minimum": 0,
 "exclusiveMinimum": true
 },
 "minItems": 1
 }
 },
 "required": [
 "id",
 "token",
 "createdAt",
 "expiresAt",
 "repoIds"
 ]
 },
 "PublicCreateScopedAccessTokenRequest": {
 "type": "object",
 "properties": {
 "repoIds": {
 "type": "array",
 "items": {
 "type": "integer",
 "minimum": 0,
 "exclusiveMinimum": true
 },
 "minItems": 1,
 "description": "Repository IDs to bind to the token. Every ID must identify a repository accessible to the API-key owner."
 }
 },
 "required": [
 "repoIds"
 ],
 "additionalProperties": false
 },
 "PublicEeUser": {
 "type": "object",
 "properties": {
Expand DownExpand Up@@ -1253,7 +1314,7 @@
 "bearerToken": {
 "type": "http",
 "scheme": "bearer",
 "description": "Bearer authentication header of the form `Bearer <token>`, where `<token>` is your API key."
 "description": "Bearer authentication header of the form `Bearer <token>`. The token may be a Sourcebot API key, OAuth access token, or scoped access token, subject to endpoint requirements."
 },
 "apiKeyHeader": {
 "type": "apiKey",
Expand DownExpand Up@@ -2266,6 +2327,161 @@
 }
 }
 },
 "/api/ee/scoped_access_token": {
 "post": {
 "operationId": "createScopedAccessToken",
 "tags": [
 "Scoped Access Tokens"
 ],
 "summary": "Create a scoped access token",
 "description": "Creates an opaque bearer token that expires exactly one hour after issuance and is restricted to the requested repositories. Repository IDs are validated atomically against the API-key owner's current access; the request fails if any ID is missing or inaccessible. Repository IDs are returned by GET /api/repos.\n\nThis endpoint requires a Sourcebot API key. Scoped access tokens, OAuth tokens, and browser sessions cannot mint another scoped access token. The returned token is independent of the API key after issuance and cannot be refreshed.",
 "security": [
 {
 "bearerToken": []
 },
 {
 "apiKeyHeader": []
 }
 ],
 "requestBody": {
 "required": true,
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicCreateScopedAccessTokenRequest"
 }
 }
 }
 },
 "responses": {
 "201": {
 "description": "Scoped access token created. The opaque token value is returned only in this response.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicCreateScopedAccessTokenResponse"
 }
 }
 }
 },
 "400": {
 "description": "Invalid request body or repository scope.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "401": {
 "description": "Missing or invalid authentication.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "403": {
 "description": "The current authentication method is not an API key, or the API-key owner is not permitted to perform this operation.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "500": {
 "description": "Unexpected token creation failure.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 }
 }
 }
 },
 "/api/ee/scoped_access_token/{id}": {
 "delete": {
 "operationId": "revokeScopedAccessToken",
 "tags": [
 "Scoped Access Tokens"
 ],
 "summary": "Revoke a scoped access token",
 "description": "Immediately revokes a scoped access token created by the authenticated API-key owner. This endpoint requires a Sourcebot API key.",
 "security": [
 {
 "bearerToken": []
 },
 {
 "apiKeyHeader": []
 }
 ],
 "parameters": [
 {
 "schema": {
 "type": "string",
 "description": "Identifier returned when the scoped access token was created."
 },
 "required": true,
 "description": "Identifier returned when the scoped access token was created.",
 "name": "id",
 "in": "path"
 }
 ],
 "responses": {
 "204": {
 "description": "Scoped access token revoked."
 },
 "401": {
 "description": "Missing or invalid authentication.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "403": {
 "description": "The current authentication method is not an API key, or the API-key owner is not permitted to perform this operation.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "404": {
 "description": "Scoped access token not found.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "500": {
 "description": "Unexpected token revocation failure.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 }
 }
 }
 },
 "/api/ee/user": {
 "get": {
 "operationId": "getUser",
Expand Down

8 changes: 8 additions & 0 deletions
docs/docs.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -189,6 +189,14 @@
 "GET /api/repos"
 ]
 },
 {
 "group": "Scoped Access Tokens",
 "icon": "key",
 "pages": [
 "POST /api/ee/scoped_access_token",
 "DELETE /api/ee/scoped_access_token/{id}"
 ]
 },
 {
 "group": "Git",
 "icon": "code-branch",
Expand Down

19 changes: 19 additions & 0 deletions
docs/docs/api-reference/authentication.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -32,3 +32,22 @@ curl -X POST https://your-sourcebot-instance.com/api/search \
 -H "Content-Type: application/json" \
 -d '{"query": "hello world", "matches": 10}'
```

## Using a scoped access token

Scoped access tokens are short-lived bearer credentials intended for clients that should only access a specific set of repositories. Create one with a Sourcebot API key by calling `POST /api/ee/scoped_access_token` with repository names:

```bash
curl -X POST https://your-sourcebot-instance.com/api/ee/scoped_access_token \
 -H "Authorization: Bearer <your-api-key>" \
 -H "Content-Type: application/json" \
 -d '{"repos": ["github.com/acme/frontend", "github.com/acme/backend"]}'
```

The response contains an opaque token beginning with `sbst_`. It expires exactly one hour after issuance, cannot be refreshed, and is returned only once. Use it as a Bearer token with public API endpoints or the Sourcebot MCP server:

```bash
Authorization: Bearer <your-scoped-access-token>
```

Repository scope is bound internally to repository IDs and is also intersected with the creating user's current repository permissions. Creating and revoking scoped access tokens requires an API key; a scoped access token cannot mint or revoke tokens.

44 changes: 44 additions & 0 deletions
packages/db/prisma/migrations/20260806033656_add_scoped_access_tokens/migration.sql

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
-- CreateTable
CREATE TABLE "ScopedAccessToken" (
 "id" TEXT NOT NULL,
 "hash" TEXT NOT NULL,
 "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
 "expiresAt" TIMESTAMP(3) NOT NULL,
 "lastUsedAt" TIMESTAMP(3),
 "createdById" TEXT NOT NULL,
 "orgId" INTEGER NOT NULL,

 CONSTRAINT "ScopedAccessToken_pkey" PRIMARY KEY ("id")
);

-- CreateTable
CREATE TABLE "ScopedAccessTokenToRepo" (
 "tokenId" TEXT NOT NULL,
 "repoId" INTEGER NOT NULL,

 CONSTRAINT "ScopedAccessTokenToRepo_pkey" PRIMARY KEY ("tokenId","repoId")
);

-- CreateIndex
CREATE UNIQUE INDEX "ScopedAccessToken_hash_key" ON "ScopedAccessToken"("hash");

-- CreateIndex
CREATE INDEX "ScopedAccessToken_createdById_orgId_expiresAt_idx" ON "ScopedAccessToken"("createdById", "orgId", "expiresAt");

-- CreateIndex
CREATE INDEX "ScopedAccessToken_expiresAt_idx" ON "ScopedAccessToken"("expiresAt");

-- CreateIndex
CREATE INDEX "ScopedAccessTokenToRepo_repoId_idx" ON "ScopedAccessTokenToRepo"("repoId");

-- AddForeignKey
ALTER TABLE "ScopedAccessToken" ADD CONSTRAINT "ScopedAccessToken_createdById_fkey" FOREIGN KEY ("createdById") REFERENCES "User"("id") ON DELETE CASCADE ON UPDATE CASCADE;

-- AddForeignKey
ALTER TABLE "ScopedAccessToken" ADD CONSTRAINT "ScopedAccessToken_orgId_fkey" FOREIGN KEY ("orgId") REFERENCES "Org"("id") ON DELETE CASCADE ON UPDATE CASCADE;

-- AddForeignKey
ALTER TABLE "ScopedAccessTokenToRepo" ADD CONSTRAINT "ScopedAccessTokenToRepo_tokenId_fkey" FOREIGN KEY ("tokenId") REFERENCES "ScopedAccessToken"("id") ON DELETE CASCADE ON UPDATE CASCADE;

-- AddForeignKey
ALTER TABLE "ScopedAccessTokenToRepo" ADD CONSTRAINT "ScopedAccessTokenToRepo_repoId_fkey" FOREIGN KEY ("repoId") REFERENCES "Repo"("id") ON DELETE CASCADE ON UPDATE CASCADE;

34 changes: 34 additions & 0 deletions
packages/db/prisma/schema.prisma

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -71,6 +71,7 @@ model Repo {
 defaultBranch String?

 permittedAccounts AccountToRepoPermission[]
 scopedAccessTokens ScopedAccessTokenToRepo[]
 permissionSyncJobs RepoPermissionSyncJob[]
 permissionSyncedAt DateTime? /// When the permissions were last synced successfully.

Expand DownExpand Up@@ -286,6 +287,7 @@ model Org {
 connections Connection[]
 repos Repo[]
 apiKeys ApiKey[]
 scopedAccessTokens ScopedAccessToken[]
 scimTokens ScimToken[]
 attachments Attachment[]
 isOnboarded Boolean @default(false)
Expand DownExpand Up@@ -454,6 +456,37 @@ model ApiKey {
 createdById String
}

model ScopedAccessToken {
 id String @id @default(cuid())
 hash String @unique

 createdAt DateTime @default(now())
 expiresAt DateTime
 lastUsedAt DateTime?

 createdBy User @relation(fields: [createdById], references: [id], onDelete: Cascade)
 createdById String

 org Org @relation(fields: [orgId], references: [id], onDelete: Cascade)
 orgId Int

 repos ScopedAccessTokenToRepo[]

 @@index([createdById, orgId, expiresAt])
 @@index([expiresAt])
}

model ScopedAccessTokenToRepo {
 token ScopedAccessToken @relation(fields: [tokenId], references: [id], onDelete: Cascade)
 tokenId String

 repo Repo @relation(fields: [repoId], references: [id], onDelete: Cascade)
 repoId Int

 @@id([tokenId, repoId])
 @@index([repoId])
}

/// Org-scoped bearer token presented by an IdP (Okta, Entra) to authenticate
/// against the SCIM provisioning endpoints. Unlike `ApiKey`, a SCIM token is
/// not tied to a user — it acts on behalf of the SCIM integration for the
Expand DownExpand Up@@ -509,6 +542,7 @@ model User {
 invites Invite[]

 apiKeys ApiKey[]
 scopedAccessTokens ScopedAccessToken[]

 chats Chat[]
 sharedChats ChatAccess[]
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
feat: add repository scoped tokens#1549

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

brendan-kellam
merged 6 commits into

from

Aug 13, 2026
 Merged


feat: add repository scoped tokens
#1549
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


6 commits


Select commit
Hold shift + click to select a range
cda8c1b

feat: add repository-scoped access tokens


brendan-kellam Aug 6, 2026
2d6c321

chore: add changelog entry for scoped access tokens


brendan-kellam Aug 6, 2026
e0b2171

Merge branch 'main' into sou-1870-scoped-access-tokens


brendan-kellam Aug 6, 2026
cdc2996

feat: scope access tokens by repository ID


brendan-kellam Aug 6, 2026
c9b3cbd

feat: gate scoped access tokens by entitlement


brendan-kellam Aug 6, 2026
e16eee2

Merge remote-tracking branch 'origin/main' into sou-1870-scoped-acces…


brendan-kellam Aug 13, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


1 change: 1 addition & 0 deletions
CHANGELOG.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Added a manually triggered cloud image release workflow for isolated internal deployments. [#1566](https://github.com/sourcebot-dev/sourcebot/pull/1566)
- Added Prometheus metrics for the web process, served on `WEB_METRICS_PORT` (default `3070`). [#1570](https://github.com/sourcebot-dev/sourcebot/pull/1570)
- Added an `http_request_duration_seconds` metric recording web request latency by route, method, and status. [#1571](https://github.com/sourcebot-dev/sourcebot/pull/1571)
- [EE] Added one-hour repository-scoped access tokens with public mint and revoke APIs. [#1549](https://github.com/sourcebot-dev/sourcebot/pull/1549)

### Fixed
- Fixed the web process being capped at a ~4GiB heap regardless of how much memory the container has, which caused multi-second garbage collection pauses on larger deployments. [#1569](https://github.com/sourcebot-dev/sourcebot/pull/1569)
Expand Down

218 changes: 217 additions & 1 deletion
docs/api-reference/sourcebot-public.openapi.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -18,6 +18,10 @@
 "name": "Git",
 "description": "Git history, diff, and file content endpoints."
 },
 {
 "name": "Scoped Access Tokens",
 "description": "Mint and revoke short-lived credentials restricted to specific repositories."
 },
 {
 "name": "System",
 "description": "System health and version endpoints."
Expand DownExpand Up@@ -1090,6 +1094,63 @@
 "$ref": "#/components/schemas/PublicCommitAuthor"
 }
 },
 "PublicCreateScopedAccessTokenResponse": {
 "type": "object",
 "properties": {
 "id": {
 "type": "string",
 "description": "Identifier used to revoke the token."
 },
 "token": {
 "type": "string",
 "pattern": "^sbst_",
 "description": "Opaque bearer token. This value is returned only when the token is created."
 },
 "createdAt": {
 "type": "string",
 "format": "date-time"
 },
 "expiresAt": {
 "type": "string",
 "format": "date-time"
 },
 "repoIds": {
 "type": "array",
 "items": {
 "type": "integer",
 "minimum": 0,
 "exclusiveMinimum": true
 },
 "minItems": 1
 }
 },
 "required": [
 "id",
 "token",
 "createdAt",
 "expiresAt",
 "repoIds"
 ]
 },
 "PublicCreateScopedAccessTokenRequest": {
 "type": "object",
 "properties": {
 "repoIds": {
 "type": "array",
 "items": {
 "type": "integer",
 "minimum": 0,
 "exclusiveMinimum": true
 },
 "minItems": 1,
 "description": "Repository IDs to bind to the token. Every ID must identify a repository accessible to the API-key owner."
 }
 },
 "required": [
 "repoIds"
 ],
 "additionalProperties": false
 },
 "PublicEeUser": {
 "type": "object",
 "properties": {
Expand DownExpand Up@@ -1253,7 +1314,7 @@
 "bearerToken": {
 "type": "http",
 "scheme": "bearer",
 "description": "Bearer authentication header of the form `Bearer <token>`, where `<token>` is your API key."
 "description": "Bearer authentication header of the form `Bearer <token>`. The token may be a Sourcebot API key, OAuth access token, or scoped access token, subject to endpoint requirements."
 },
 "apiKeyHeader": {
 "type": "apiKey",
Expand DownExpand Up@@ -2266,6 +2327,161 @@
 }
 }
 },
 "/api/ee/scoped_access_token": {
 "post": {
 "operationId": "createScopedAccessToken",
 "tags": [
 "Scoped Access Tokens"
 ],
 "summary": "Create a scoped access token",
 "description": "Creates an opaque bearer token that expires exactly one hour after issuance and is restricted to the requested repositories. Repository IDs are validated atomically against the API-key owner's current access; the request fails if any ID is missing or inaccessible. Repository IDs are returned by GET /api/repos.\n\nThis endpoint requires a Sourcebot API key. Scoped access tokens, OAuth tokens, and browser sessions cannot mint another scoped access token. The returned token is independent of the API key after issuance and cannot be refreshed.",
 "security": [
 {
 "bearerToken": []
 },
 {
 "apiKeyHeader": []
 }
 ],
 "requestBody": {
 "required": true,
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicCreateScopedAccessTokenRequest"
 }
 }
 }
 },
 "responses": {
 "201": {
 "description": "Scoped access token created. The opaque token value is returned only in this response.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicCreateScopedAccessTokenResponse"
 }
 }
 }
 },
 "400": {
 "description": "Invalid request body or repository scope.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "401": {
 "description": "Missing or invalid authentication.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "403": {
 "description": "The current authentication method is not an API key, or the API-key owner is not permitted to perform this operation.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "500": {
 "description": "Unexpected token creation failure.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 }
 }
 }
 },
 "/api/ee/scoped_access_token/{id}": {
 "delete": {
 "operationId": "revokeScopedAccessToken",
 "tags": [
 "Scoped Access Tokens"
 ],
 "summary": "Revoke a scoped access token",
 "description": "Immediately revokes a scoped access token created by the authenticated API-key owner. This endpoint requires a Sourcebot API key.",
 "security": [
 {
 "bearerToken": []
 },
 {
 "apiKeyHeader": []
 }
 ],
 "parameters": [
 {
 "schema": {
 "type": "string",
 "description": "Identifier returned when the scoped access token was created."
 },
 "required": true,
 "description": "Identifier returned when the scoped access token was created.",
 "name": "id",
 "in": "path"
 }
 ],
 "responses": {
 "204": {
 "description": "Scoped access token revoked."
 },
 "401": {
 "description": "Missing or invalid authentication.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "403": {
 "description": "The current authentication method is not an API key, or the API-key owner is not permitted to perform this operation.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "404": {
 "description": "Scoped access token not found.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "500": {
 "description": "Unexpected token revocation failure.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 }
 }
 }
 },
 "/api/ee/user": {
 "get": {
 "operationId": "getUser",
Expand Down

8 changes: 8 additions & 0 deletions
docs/docs.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -189,6 +189,14 @@
 "GET /api/repos"
 ]
 },
 {
 "group": "Scoped Access Tokens",
 "icon": "key",
 "pages": [
 "POST /api/ee/scoped_access_token",
 "DELETE /api/ee/scoped_access_token/{id}"
 ]
 },
 {
 "group": "Git",
 "icon": "code-branch",
Expand Down

19 changes: 19 additions & 0 deletions
docs/docs/api-reference/authentication.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -32,3 +32,22 @@ curl -X POST https://your-sourcebot-instance.com/api/search \
 -H "Content-Type: application/json" \
 -d '{"query": "hello world", "matches": 10}'
```

## Using a scoped access token

Scoped access tokens are short-lived bearer credentials intended for clients that should only access a specific set of repositories. Create one with a Sourcebot API key by calling `POST /api/ee/scoped_access_token` with repository names:

```bash
curl -X POST https://your-sourcebot-instance.com/api/ee/scoped_access_token \
 -H "Authorization: Bearer <your-api-key>" \
 -H "Content-Type: application/json" \
 -d '{"repos": ["github.com/acme/frontend", "github.com/acme/backend"]}'
```

The response contains an opaque token beginning with `sbst_`. It expires exactly one hour after issuance, cannot be refreshed, and is returned only once. Use it as a Bearer token with public API endpoints or the Sourcebot MCP server:

```bash
Authorization: Bearer <your-scoped-access-token>
```

Repository scope is bound internally to repository IDs and is also intersected with the creating user's current repository permissions. Creating and revoking scoped access tokens requires an API key; a scoped access token cannot mint or revoke tokens.

44 changes: 44 additions & 0 deletions
packages/db/prisma/migrations/20260806033656_add_scoped_access_tokens/migration.sql

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
-- CreateTable
CREATE TABLE "ScopedAccessToken" (
 "id" TEXT NOT NULL,
 "hash" TEXT NOT NULL,
 "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
 "expiresAt" TIMESTAMP(3) NOT NULL,
 "lastUsedAt" TIMESTAMP(3),
 "createdById" TEXT NOT NULL,
 "orgId" INTEGER NOT NULL,

 CONSTRAINT "ScopedAccessToken_pkey" PRIMARY KEY ("id")
);

-- CreateTable
CREATE TABLE "ScopedAccessTokenToRepo" (
 "tokenId" TEXT NOT NULL,
 "repoId" INTEGER NOT NULL,

 CONSTRAINT "ScopedAccessTokenToRepo_pkey" PRIMARY KEY ("tokenId","repoId")
);

-- CreateIndex
CREATE UNIQUE INDEX "ScopedAccessToken_hash_key" ON "ScopedAccessToken"("hash");

-- CreateIndex
CREATE INDEX "ScopedAccessToken_createdById_orgId_expiresAt_idx" ON "ScopedAccessToken"("createdById", "orgId", "expiresAt");

-- CreateIndex
CREATE INDEX "ScopedAccessToken_expiresAt_idx" ON "ScopedAccessToken"("expiresAt");

-- CreateIndex
CREATE INDEX "ScopedAccessTokenToRepo_repoId_idx" ON "ScopedAccessTokenToRepo"("repoId");

-- AddForeignKey
ALTER TABLE "ScopedAccessToken" ADD CONSTRAINT "ScopedAccessToken_createdById_fkey" FOREIGN KEY ("createdById") REFERENCES "User"("id") ON DELETE CASCADE ON UPDATE CASCADE;

-- AddForeignKey
ALTER TABLE "ScopedAccessToken" ADD CONSTRAINT "ScopedAccessToken_orgId_fkey" FOREIGN KEY ("orgId") REFERENCES "Org"("id") ON DELETE CASCADE ON UPDATE CASCADE;

-- AddForeignKey
ALTER TABLE "ScopedAccessTokenToRepo" ADD CONSTRAINT "ScopedAccessTokenToRepo_tokenId_fkey" FOREIGN KEY ("tokenId") REFERENCES "ScopedAccessToken"("id") ON DELETE CASCADE ON UPDATE CASCADE;

-- AddForeignKey
ALTER TABLE "ScopedAccessTokenToRepo" ADD CONSTRAINT "ScopedAccessTokenToRepo_repoId_fkey" FOREIGN KEY ("repoId") REFERENCES "Repo"("id") ON DELETE CASCADE ON UPDATE CASCADE;

34 changes: 34 additions & 0 deletions
packages/db/prisma/schema.prisma

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -71,6 +71,7 @@ model Repo {
 defaultBranch String?

 permittedAccounts AccountToRepoPermission[]
 scopedAccessTokens ScopedAccessTokenToRepo[]
 permissionSyncJobs RepoPermissionSyncJob[]
 permissionSyncedAt DateTime? /// When the permissions were last synced successfully.

Expand DownExpand Up@@ -286,6 +287,7 @@ model Org {
 connections Connection[]
 repos Repo[]
 apiKeys ApiKey[]
 scopedAccessTokens ScopedAccessToken[]
 scimTokens ScimToken[]
 attachments Attachment[]
 isOnboarded Boolean @default(false)
Expand DownExpand Up@@ -454,6 +456,37 @@ model ApiKey {
 createdById String
}

model ScopedAccessToken {
 id String @id @default(cuid())
 hash String @unique

 createdAt DateTime @default(now())
 expiresAt DateTime
 lastUsedAt DateTime?

 createdBy User @relation(fields: [createdById], references: [id], onDelete: Cascade)
 createdById String

 org Org @relation(fields: [orgId], references: [id], onDelete: Cascade)
 orgId Int

 repos ScopedAccessTokenToRepo[]

 @@index([createdById, orgId, expiresAt])
 @@index([expiresAt])
}

model ScopedAccessTokenToRepo {
 token ScopedAccessToken @relation(fields: [tokenId], references: [id], onDelete: Cascade)
 tokenId String

 repo Repo @relation(fields: [repoId], references: [id], onDelete: Cascade)
 repoId Int

 @@id([tokenId, repoId])
 @@index([repoId])
}

/// Org-scoped bearer token presented by an IdP (Okta, Entra) to authenticate
/// against the SCIM provisioning endpoints. Unlike `ApiKey`, a SCIM token is
/// not tied to a user — it acts on behalf of the SCIM integration for the
Expand DownExpand Up@@ -509,6 +542,7 @@ model User {
 invites Invite[]

 apiKeys ApiKey[]
 scopedAccessTokens ScopedAccessToken[]

 chats Chat[]
 sharedChats ChatAccess[]
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
feat: add repository scoped tokens#1549

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

brendan-kellam
merged 6 commits into

from

Aug 13, 2026
 Merged


feat: add repository scoped tokens
#1549
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


6 commits


Select commit
Hold shift + click to select a range
cda8c1b

feat: add repository-scoped access tokens


brendan-kellam Aug 6, 2026
2d6c321

chore: add changelog entry for scoped access tokens


brendan-kellam Aug 6, 2026
e0b2171

Merge branch 'main' into sou-1870-scoped-access-tokens


brendan-kellam Aug 6, 2026
cdc2996

feat: scope access tokens by repository ID


brendan-kellam Aug 6, 2026
c9b3cbd

feat: gate scoped access tokens by entitlement


brendan-kellam Aug 6, 2026
e16eee2

Merge remote-tracking branch 'origin/main' into sou-1870-scoped-acces…


brendan-kellam Aug 13, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


1 change: 1 addition & 0 deletions
CHANGELOG.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Added a manually triggered cloud image release workflow for isolated internal deployments. [#1566](https://github.com/sourcebot-dev/sourcebot/pull/1566)
- Added Prometheus metrics for the web process, served on `WEB_METRICS_PORT` (default `3070`). [#1570](https://github.com/sourcebot-dev/sourcebot/pull/1570)
- Added an `http_request_duration_seconds` metric recording web request latency by route, method, and status. [#1571](https://github.com/sourcebot-dev/sourcebot/pull/1571)
- [EE] Added one-hour repository-scoped access tokens with public mint and revoke APIs. [#1549](https://github.com/sourcebot-dev/sourcebot/pull/1549)

### Fixed
- Fixed the web process being capped at a ~4GiB heap regardless of how much memory the container has, which caused multi-second garbage collection pauses on larger deployments. [#1569](https://github.com/sourcebot-dev/sourcebot/pull/1569)
Expand Down

218 changes: 217 additions & 1 deletion
docs/api-reference/sourcebot-public.openapi.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -18,6 +18,10 @@
 "name": "Git",
 "description": "Git history, diff, and file content endpoints."
 },
 {
 "name": "Scoped Access Tokens",
 "description": "Mint and revoke short-lived credentials restricted to specific repositories."
 },
 {
 "name": "System",
 "description": "System health and version endpoints."
Expand DownExpand Up@@ -1090,6 +1094,63 @@
 "$ref": "#/components/schemas/PublicCommitAuthor"
 }
 },
 "PublicCreateScopedAccessTokenResponse": {
 "type": "object",
 "properties": {
 "id": {
 "type": "string",
 "description": "Identifier used to revoke the token."
 },
 "token": {
 "type": "string",
 "pattern": "^sbst_",
 "description": "Opaque bearer token. This value is returned only when the token is created."
 },
 "createdAt": {
 "type": "string",
 "format": "date-time"
 },
 "expiresAt": {
 "type": "string",
 "format": "date-time"
 },
 "repoIds": {
 "type": "array",
 "items": {
 "type": "integer",
 "minimum": 0,
 "exclusiveMinimum": true
 },
 "minItems": 1
 }
 },
 "required": [
 "id",
 "token",
 "createdAt",
 "expiresAt",
 "repoIds"
 ]
 },
 "PublicCreateScopedAccessTokenRequest": {
 "type": "object",
 "properties": {
 "repoIds": {
 "type": "array",
 "items": {
 "type": "integer",
 "minimum": 0,
 "exclusiveMinimum": true
 },
 "minItems": 1,
 "description": "Repository IDs to bind to the token. Every ID must identify a repository accessible to the API-key owner."
 }
 },
 "required": [
 "repoIds"
 ],
 "additionalProperties": false
 },
 "PublicEeUser": {
 "type": "object",
 "properties": {
Expand DownExpand Up@@ -1253,7 +1314,7 @@
 "bearerToken": {
 "type": "http",
 "scheme": "bearer",
 "description": "Bearer authentication header of the form `Bearer <token>`, where `<token>` is your API key."
 "description": "Bearer authentication header of the form `Bearer <token>`. The token may be a Sourcebot API key, OAuth access token, or scoped access token, subject to endpoint requirements."
 },
 "apiKeyHeader": {
 "type": "apiKey",
Expand DownExpand Up@@ -2266,6 +2327,161 @@
 }
 }
 },
 "/api/ee/scoped_access_token": {
 "post": {
 "operationId": "createScopedAccessToken",
 "tags": [
 "Scoped Access Tokens"
 ],
 "summary": "Create a scoped access token",
 "description": "Creates an opaque bearer token that expires exactly one hour after issuance and is restricted to the requested repositories. Repository IDs are validated atomically against the API-key owner's current access; the request fails if any ID is missing or inaccessible. Repository IDs are returned by GET /api/repos.\n\nThis endpoint requires a Sourcebot API key. Scoped access tokens, OAuth tokens, and browser sessions cannot mint another scoped access token. The returned token is independent of the API key after issuance and cannot be refreshed.",
 "security": [
 {
 "bearerToken": []
 },
 {
 "apiKeyHeader": []
 }
 ],
 "requestBody": {
 "required": true,
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicCreateScopedAccessTokenRequest"
 }
 }
 }
 },
 "responses": {
 "201": {
 "description": "Scoped access token created. The opaque token value is returned only in this response.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicCreateScopedAccessTokenResponse"
 }
 }
 }
 },
 "400": {
 "description": "Invalid request body or repository scope.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "401": {
 "description": "Missing or invalid authentication.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "403": {
 "description": "The current authentication method is not an API key, or the API-key owner is not permitted to perform this operation.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "500": {
 "description": "Unexpected token creation failure.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 }
 }
 }
 },
 "/api/ee/scoped_access_token/{id}": {
 "delete": {
 "operationId": "revokeScopedAccessToken",
 "tags": [
 "Scoped Access Tokens"
 ],
 "summary": "Revoke a scoped access token",
 "description": "Immediately revokes a scoped access token created by the authenticated API-key owner. This endpoint requires a Sourcebot API key.",
 "security": [
 {
 "bearerToken": []
 },
 {
 "apiKeyHeader": []
 }
 ],
 "parameters": [
 {
 "schema": {
 "type": "string",
 "description": "Identifier returned when the scoped access token was created."
 },
 "required": true,
 "description": "Identifier returned when the scoped access token was created.",
 "name": "id",
 "in": "path"
 }
 ],
 "responses": {
 "204": {
 "description": "Scoped access token revoked."
 },
 "401": {
 "description": "Missing or invalid authentication.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "403": {
 "description": "The current authentication method is not an API key, or the API-key owner is not permitted to perform this operation.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "404": {
 "description": "Scoped access token not found.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 },
 "500": {
 "description": "Unexpected token revocation failure.",
 "content": {
 "application/json": {
 "schema": {
 "$ref": "#/components/schemas/PublicApiServiceError"
 }
 }
 }
 }
 }
 }
 },
 "/api/ee/user": {
 "get": {
 "operationId": "getUser",
Expand Down

8 changes: 8 additions & 0 deletions
docs/docs.json

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -189,6 +189,14 @@
 "GET /api/repos"
 ]
 },
 {
 "group": "Scoped Access Tokens",
 "icon": "key",
 "pages": [
 "POST /api/ee/scoped_access_token",
 "DELETE /api/ee/scoped_access_token/{id}"
 ]
 },
 {
 "group": "Git",
 "icon": "code-branch",
Expand Down

19 changes: 19 additions & 0 deletions
docs/docs/api-reference/authentication.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -32,3 +32,22 @@ curl -X POST https://your-sourcebot-instance.com/api/search \
 -H "Content-Type: application/json" \
 -d '{"query": "hello world", "matches": 10}'
```

## Using a scoped access token

Scoped access tokens are short-lived bearer credentials intended for clients that should only access a specific set of repositories. Create one with a Sourcebot API key by calling `POST /api/ee/scoped_access_token` with repository names:

```bash
curl -X POST https://your-sourcebot-instance.com/api/ee/scoped_access_token \
 -H "Authorization: Bearer <your-api-key>" \
 -H "Content-Type: application/json" \
 -d '{"repos": ["github.com/acme/frontend", "github.com/acme/backend"]}'
```

The response contains an opaque token beginning with `sbst_`. It expires exactly one hour after issuance, cannot be refreshed, and is returned only once. Use it as a Bearer token with public API endpoints or the Sourcebot MCP server:

```bash
Authorization: Bearer <your-scoped-access-token>
```

Repository scope is bound internally to repository IDs and is also intersected with the creating user's current repository permissions. Creating and revoking scoped access tokens requires an API key; a scoped access token cannot mint or revoke tokens.

44 changes: 44 additions & 0 deletions
packages/db/prisma/migrations/20260806033656_add_scoped_access_tokens/migration.sql

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
-- CreateTable
CREATE TABLE "ScopedAccessToken" (
 "id" TEXT NOT NULL,
 "hash" TEXT NOT NULL,
 "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
 "expiresAt" TIMESTAMP(3) NOT NULL,
 "lastUsedAt" TIMESTAMP(3),
 "createdById" TEXT NOT NULL,
 "orgId" INTEGER NOT NULL,

 CONSTRAINT "ScopedAccessToken_pkey" PRIMARY KEY ("id")
);

-- CreateTable
CREATE TABLE "ScopedAccessTokenToRepo" (
 "tokenId" TEXT NOT NULL,
 "repoId" INTEGER NOT NULL,

 CONSTRAINT "ScopedAccessTokenToRepo_pkey" PRIMARY KEY ("tokenId","repoId")
);

-- CreateIndex
CREATE UNIQUE INDEX "ScopedAccessToken_hash_key" ON "ScopedAccessToken"("hash");

-- CreateIndex
CREATE INDEX "ScopedAccessToken_createdById_orgId_expiresAt_idx" ON "ScopedAccessToken"("createdById", "orgId", "expiresAt");

-- CreateIndex
CREATE INDEX "ScopedAccessToken_expiresAt_idx" ON "ScopedAccessToken"("expiresAt");

-- CreateIndex
CREATE INDEX "ScopedAccessTokenToRepo_repoId_idx" ON "ScopedAccessTokenToRepo"("repoId");

-- AddForeignKey
ALTER TABLE "ScopedAccessToken" ADD CONSTRAINT "ScopedAccessToken_createdById_fkey" FOREIGN KEY ("createdById") REFERENCES "User"("id") ON DELETE CASCADE ON UPDATE CASCADE;

-- AddForeignKey
ALTER TABLE "ScopedAccessToken" ADD CONSTRAINT "ScopedAccessToken_orgId_fkey" FOREIGN KEY ("orgId") REFERENCES "Org"("id") ON DELETE CASCADE ON UPDATE CASCADE;

-- AddForeignKey
ALTER TABLE "ScopedAccessTokenToRepo" ADD CONSTRAINT "ScopedAccessTokenToRepo_tokenId_fkey" FOREIGN KEY ("tokenId") REFERENCES "ScopedAccessToken"("id") ON DELETE CASCADE ON UPDATE CASCADE;

-- AddForeignKey
ALTER TABLE "ScopedAccessTokenToRepo" ADD CONSTRAINT "ScopedAccessTokenToRepo_repoId_fkey" FOREIGN KEY ("repoId") REFERENCES "Repo"("id") ON DELETE CASCADE ON UPDATE CASCADE;

34 changes: 34 additions & 0 deletions
packages/db/prisma/schema.prisma

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -71,6 +71,7 @@ model Repo {
 defaultBranch String?

 permittedAccounts AccountToRepoPermission[]
 scopedAccessTokens ScopedAccessTokenToRepo[]
 permissionSyncJobs RepoPermissionSyncJob[]
 permissionSyncedAt DateTime? /// When the permissions were last synced successfully.

Expand DownExpand Up@@ -286,6 +287,7 @@ model Org {
 connections Connection[]
 repos Repo[]
 apiKeys ApiKey[]
 scopedAccessTokens ScopedAccessToken[]
 scimTokens ScimToken[]
 attachments Attachment[]
 isOnboarded Boolean @default(false)
Expand DownExpand Up@@ -454,6 +456,37 @@ model ApiKey {
 createdById String
}

model ScopedAccessToken {
 id String @id @default(cuid())
 hash String @unique

 createdAt DateTime @default(now())
 expiresAt DateTime
 lastUsedAt DateTime?

 createdBy User @relation(fields: [createdById], references: [id], onDelete: Cascade)
 createdById String

 org Org @relation(fields: [orgId], references: [id], onDelete: Cascade)
 orgId Int

 repos ScopedAccessTokenToRepo[]

 @@index([createdById, orgId, expiresAt])
 @@index([expiresAt])
}

model ScopedAccessTokenToRepo {
 token ScopedAccessToken @relation(fields: [tokenId], references: [id], onDelete: Cascade)
 tokenId String

 repo Repo @relation(fields: [repoId], references: [id], onDelete: Cascade)
 repoId Int

 @@id([tokenId, repoId])
 @@index([repoId])
}

/// Org-scoped bearer token presented by an IdP (Okta, Entra) to authenticate
/// against the SCIM provisioning endpoints. Unlike `ApiKey`, a SCIM token is
/// not tied to a user — it acts on behalf of the SCIM integration for the
Expand DownExpand Up@@ -509,6 +542,7 @@ model User {
 invites Invite[]

 apiKeys ApiKey[]
 scopedAccessTokens ScopedAccessToken[]

 chats Chat[]
 sharedChats ChatAccess[]
Expand Down
Loading
Loading