docs(api-reference/authentication): scoped access token example uses wrong field name and value type

[Harsh23Kashyap]

Title: docs(api-reference/authentication): scoped access token example uses wrong field name and value type

The "Using a scoped access token" section in docs/docs/api-reference/authentication.mdx (lines 36-57) shows a POST /api/ee/scoped_access_token example with a request body that the actual API will reject with a 400.

Current behavior in the docs

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"]}'

What the code actually accepts

packages/web/src/ee/features/scopedAccessTokens/api.ts:12-14:

export const createScopedAccessTokenRequestSchema = z.object({
 repoIds: z.array(z.number().int().positive()).min(1),
}).strict();

So the actual request body is { "repoIds": [1, 2, 3] } (positive integers, no host prefix). The docs example has three problems:

1. Wrong field name: repos vs the schema's repoIds. A .strict() schema will fail validation on the extra key, so the docs example returns 400.
2. Wrong value type: string array vs positive integer array. z.number() rejects the strings.
3. Wrong value format: the doc's example values include a host prefix (github.com/...) that the API has no way to resolve, since it expects integer IDs from the Repo table.

Additional gaps in the same section

• The response shape is not documented anywhere on the page. POST returns { id, token, createdAt, expiresAt, repoIds } per publicCreateScopedAccessTokenResponseSchema (packages/web/src/openapi/publicApiSchemas.ts:121-128). The page mentions only the opaque sbst_ token prefix and the 1-hour TTL but does not show the caller how to capture the id they need to revoke the token later.
• The revoke endpoint (DELETE /api/ee/scoped_access_token/{id}) is not documented at all in the .mdx. The OpenAPI spec documents it (it accepts a path parameter that is the id from the create response, not the token value) but the page never tells users how to call it.
• The page does not say where the integer IDs come from. Users have to call GET /api/repos first to get the IDs; the page assumes they already know them.

Proposed fix

In docs/docs/api-reference/authentication.mdx:

• Replace the request body in the create example with the schema-valid {"repoIds": [1, 2, 3]} shape, with a one-line note that the IDs are the integer Repo.id values from GET /api/repos.
• Add a short create-response example showing the JSON body the API returns, so readers can see the id they need for revocation.
• Add a DELETE /api/ee/scoped_access_token/{id} example, also with the Authorization: Bearer <api-key> header (per the OpenAPI spec, the 403 response says "The current authentication method is not an API key, or the API-key owner is not permitted to perform this operation", confirming the revoke endpoint requires an API key, not another scoped token).

No code or behavior change; no changelog entry needed (docs only, matching the pattern of #1579).

Acceptance criteria

• The create curl example uses the field name repoIds and an array of positive integer values.
• The create response shape is documented in the .mdx (or the user is pointed at the OpenAPI spec component for the full schema).
• A DELETE /api/ee/scoped_access_token/{id} example exists in the same section.
• A GET /api/repos pointer is included so a reader who only knows a repo's display name can find the integer ID.
• docs/api-reference/sourcebot-public.openapi.json is unchanged (the OpenAPI spec is already in sync with the code; the .mdx is the only stale artifact).