feat: add repository scoped tokens

CHANGELOG.md

@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- [EE] Added one-hour repository-scoped access tokens with public mint and revoke APIs. [#1549](https://github.com/sourcebot-dev/sourcebot/pull/1549)
 - [EE] Added guided reconnection for MCP connector authentication failures during Ask Sourcebot agent turns. [#1548](https://github.com/sourcebot-dev/sourcebot/pull/1548)
 
 ### Removed

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

@@ -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."
@@ -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": {
@@ -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",
@@ -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",

docs/docs.json

@@ -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",

docs/docs/api-reference/authentication.mdx

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

packages/db/prisma/migrations/20260806033656_add_scoped_access_tokens/migration.sql

@@ -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;

packages/db/prisma/schema.prisma

@@ -71,6 +71,7 @@ model Repo {
   defaultBranch         String?
 
   permittedAccounts  AccountToRepoPermission[]
+  scopedAccessTokens ScopedAccessTokenToRepo[]
   permissionSyncJobs RepoPermissionSyncJob[]
   permissionSyncedAt    DateTime? /// When the permissions were last synced successfully.
 
@@ -286,6 +287,7 @@ model Org {
   connections Connection[]
   repos       Repo[]
   apiKeys     ApiKey[]
+  scopedAccessTokens ScopedAccessToken[]
   scimTokens  ScimToken[]
   attachments Attachment[]
   isOnboarded Boolean      @default(false)
@@ -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
@@ -509,6 +542,7 @@ model User {
   invites Invite[]
 
   apiKeys ApiKey[]
+  scopedAccessTokens ScopedAccessToken[]
 
   chats Chat[]
   sharedChats ChatAccess[]