From 8928f4511ad04ebd45b118c354215066dddfa6a3 Mon Sep 17 00:00:00 2001 From: Brendan Kellam Date: Thu, 13 Aug 2026 09:48:49 -0700 Subject: [PATCH] docs: clarify scoped access token entitlement --- .../sourcebot-public.openapi.json | 10 ++++++++-- docs/docs/api-reference/authentication.mdx | 4 ++++ packages/web/src/openapi/publicApiDocument.ts | 18 ++++++++++++++---- 3 files changed, 26 insertions(+), 6 deletions(-) diff --git a/docs/api-reference/sourcebot-public.openapi.json b/docs/api-reference/sourcebot-public.openapi.json index 6855e15a5..b5af40292 100644 --- a/docs/api-reference/sourcebot-public.openapi.json +++ b/docs/api-reference/sourcebot-public.openapi.json @@ -2423,7 +2423,7 @@ "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.", + "description": "Creates an opaque bearer token that expires exactly one hour after issuance and is restricted to the requested repositories.", "security": [ { "bearerToken": [] @@ -2432,6 +2432,9 @@ "apiKeyHeader": [] } ], + "x-mint": { + "content": "\nThe scoped access token APIs require a custom entitlement. To request access, contact [team@sourcebot.dev](mailto:team@sourcebot.dev).\n" + }, "requestBody": { "required": true, "content": { @@ -2503,7 +2506,7 @@ "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.", + "description": "Immediately revokes a scoped access token created by the authenticated API-key owner.", "security": [ { "bearerToken": [] @@ -2512,6 +2515,9 @@ "apiKeyHeader": [] } ], + "x-mint": { + "content": "\nThe scoped access token APIs require a custom entitlement. To request access, contact [team@sourcebot.dev](mailto:team@sourcebot.dev).\n" + }, "parameters": [ { "schema": { diff --git a/docs/docs/api-reference/authentication.mdx b/docs/docs/api-reference/authentication.mdx index 03b27b97a..f3e10ae21 100644 --- a/docs/docs/api-reference/authentication.mdx +++ b/docs/docs/api-reference/authentication.mdx @@ -35,6 +35,10 @@ curl -X POST https://your-sourcebot-instance.com/api/search \ ## Using a scoped access token + +The scoped access token APIs require a custom entitlement. To request access, contact [team@sourcebot.dev](mailto:team@sourcebot.dev). + + 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 diff --git a/packages/web/src/openapi/publicApiDocument.ts b/packages/web/src/openapi/publicApiDocument.ts index 23e88b97b..8c07ee274 100644 --- a/packages/web/src/openapi/publicApiDocument.ts +++ b/packages/web/src/openapi/publicApiDocument.ts @@ -50,6 +50,12 @@ This API is only available with an active Sourcebot license. [More information]( `; +const SCOPED_ACCESS_TOKEN_ENTITLEMENT_INFO = dedent` + +The scoped access token APIs require a custom entitlement. To request access, contact [team@sourcebot.dev](mailto:team@sourcebot.dev). + +`; + const publicFileTreeNodeSchema: SchemaObject = { type: 'object', properties: { @@ -456,9 +462,7 @@ export function createPublicOpenApiDocument(version: string) { tags: [scopedAccessTokensTag.name], summary: 'Create a scoped access token', description: dedent` - 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. - - This 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. + Creates an opaque bearer token that expires exactly one hour after issuance and is restricted to the requested repositories. `, security: [ { [securitySchemeNames.bearerToken]: [] }, @@ -480,6 +484,9 @@ export function createPublicOpenApiDocument(version: string) { 403: errorJson('The current authentication method is not an API key, or the API-key owner is not permitted to perform this operation.'), 500: errorJson('Unexpected token creation failure.'), }, + 'x-mint': { + content: SCOPED_ACCESS_TOKEN_ENTITLEMENT_INFO, + }, }); registry.registerPath({ @@ -488,7 +495,7 @@ export function createPublicOpenApiDocument(version: string) { operationId: 'revokeScopedAccessToken', tags: [scopedAccessTokensTag.name], 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.', + description: 'Immediately revokes a scoped access token created by the authenticated API-key owner.', security: [ { [securitySchemeNames.bearerToken]: [] }, { [securitySchemeNames.apiKeyHeader]: [] }, @@ -507,6 +514,9 @@ export function createPublicOpenApiDocument(version: string) { 404: errorJson('Scoped access token not found.'), 500: errorJson('Unexpected token revocation failure.'), }, + 'x-mint': { + content: SCOPED_ACCESS_TOKEN_ENTITLEMENT_INFO, + }, }); // EE: User Management