fix(auth): complete OAuth integration and lifecycle guarantees

Author: waleedlatif1

.github/workflows/test-build.yml

@@ -8,6 +8,80 @@ permissions:
   contents: read
 
 jobs:
+  oauth-postgres:
+    name: OAuth PostgreSQL (${{ matrix.provision }})
+    runs-on: ${{ (vars.CI_PROVIDER == '' || vars.CI_PROVIDER == 'blacksmith') && 'blacksmith-8vcpu-ubuntu-2404' || 'ubuntu-latest' }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        provision: [push, migrate]
+    services:
+      postgres:
+        image: pgvector/pgvector:pg17
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: sim_oauth
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres -d sim_oauth"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+    env:
+      DATABASE_URL: postgresql://postgres:postgres@127.0.0.1:5432/sim_oauth
+      OAUTH_TOKEN_FAMILY_TEST_DATABASE_URL: postgresql://postgres:postgres@127.0.0.1:5432/sim_oauth
+      BETTER_AUTH_SECRET: oauth-postgres-ci-secret-at-least-32-characters
+      OAUTH_PROVIDER_ENABLED: 'true'
+      NEXT_PUBLIC_APP_URL: https://test.sim.ai
+      ENCRYPTION_KEY: '0000000000000000000000000000000000000000000000000000000000000000'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
+        with:
+          bun-version: 1.4.1
+
+      - name: Setup Node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
+        with:
+          node-version: 24
+
+      - name: Mount Bun cache
+        uses: ./.github/actions/cache-mount
+        with:
+          provider: ${{ vars.CI_PROVIDER }}
+          key: ${{ github.repository }}-bun-cache-${{ github.event_name }}${{ github.event.pull_request.head.repo.fork && '-fork' || '' }}
+          path: ~/.bun/install/cache
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile --ignore-scripts
+
+      - name: Provision a fresh database through the supported command
+        working-directory: packages/db
+        run: |
+          bun -e 'import postgres from "postgres"; const sql = postgres(process.env.DATABASE_URL); for (const extension of ["vector", "btree_gin", "pg_trgm"]) await sql`CREATE EXTENSION IF NOT EXISTS ${sql(extension)}`; await sql.end()'
+          bun run db:${{ matrix.provision }}
+
+      - name: Verify migration replay is a no-op
+        if: matrix.provision == 'migrate'
+        working-directory: packages/db
+        run: bun run db:migrate
+
+      - name: Verify provider issuance and token lifecycle in PostgreSQL
+        working-directory: apps/sim
+        run: >-
+          bunx vitest run
+          lib/auth/oauth-token-family.postgres.test.ts
+          lib/auth/oauth-provider-lifecycle.postgres.test.ts
+          app/api/auth/oauth2/token/route.postgres.test.ts
+          lib/auth/sim-auth-adapter.test.ts
+
   test-build:
     name: Lint and Test
     runs-on: ${{ (vars.CI_PROVIDER == '' || vars.CI_PROVIDER == 'blacksmith') && 'blacksmith-8vcpu-ubuntu-2404' || 'ubuntu-latest' }}

apps/docs/content/docs/api-reference/authentication.mdx

@@ -1,12 +1,14 @@
 ---
 title: Authentication
-description: API key types, generation, and how to authenticate requests
+description: Authenticate with API keys or delegated OAuth access tokens
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
 
-To access the Sim API, you need an API key. Sim supports two types of API keys — **personal keys** and **workspace keys** — each with different billing and access behaviors.
+The Sim API accepts API keys and, when enabled by your deployment, OAuth access tokens. API keys support automation and the SDKs. OAuth lets the CLI and registered applications act on your behalf with permissions you approve.
+
+Sim supports two types of API keys — **personal keys** and **workspace keys** — each with different billing and access behaviors.
 
 ## Key Types
 
@@ -87,6 +89,27 @@ API keys authenticate access to:
 - **MCP servers** — authenticate connections to deployed MCP servers
 - **SDKs** — the [Python](/api-reference/python) and [TypeScript](/api-reference/typescript) SDKs use API keys for all operations
 
+## OAuth access tokens
+
+Use `sim login` to authorize the CLI in your browser, or `sim login --read-only` to request read access. The CLI stores the login locally and refreshes access tokens automatically. See [CLI authentication](/cli/authentication) for profiles, sign-in, and sign-out.
+
+Registered OAuth applications send access tokens in the `Authorization` header:
+
+```bash
+curl https://www.sim.ai/api/v2/workspaces \
+  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
+```
+
+| Scope | Access |
+| --- | --- |
+| `api:read` | Read operations, including searches sent as POST requests |
+| `api:write` | Mutations and execution, including operations that can start external work |
+| `offline_access` | Refresh tokens for continued access after the access token expires |
+
+Scopes limit what an application may do; your current workspace membership and role still apply. Each endpoint documents its required scope. Some GET endpoints that perform external discovery require `api:write`, so HTTP method alone does not determine the permission.
+
+Manage grants in **Settings** → **Authorized apps**. Revoking an application signs out all of its logins. `sim logout` revokes the current CLI login and removes it from your machine. The Python and TypeScript SDKs currently use API keys; they do not manage OAuth sign-in or refresh tokens.
+
 ## Security
 
 - Keys use the `sk-sim-` prefix and are encrypted at rest

apps/docs/content/docs/api-reference/getting-started.mdx

@@ -26,7 +26,7 @@ Download the [complete OpenAPI 3.1 specification](/openapi.json) as JSON for cli
 <Step>
 ### Get your API key
 
-Go to the Sim platform and navigate to **Settings**, then go to **Sim Keys** and click **Create**. See [Authentication](/api-reference/authentication) for details on key types.
+Open **Account settings** → **Sim API keys** to create a personal key, or **Workspace settings** → **Sim API keys** for a workspace key. These examples and the SDKs use API keys; the CLI also supports browser sign-in with `sim login`. See [Authentication](/api-reference/authentication) for key types and OAuth permissions.
 </Step>
 
 <Step>

apps/docs/openapi-v2-billing.json

@@ -39,7 +39,9 @@
       "get": {
         "operationId": "getBillingStatus",
         "summary": "Get Billing Status",
-        "description": "Return the current plan, billing standing, credit allowance, and storage quota. `credits` and `storage` report the payer's pooled allowances and are null unless the caller can manage that payer's billing; they are always null for a workspace API key. Billing history lives at `GET /api/v2/billing/logs`.",
+        "description": "Return the current plan, billing standing, credit allowance, and storage quota. `credits` and `storage` report the payer's pooled allowances and are null unless the caller can manage that payer's billing; they are always null for a workspace API key. Billing history lives at `GET /api/v2/billing/logs`.\n\nOAuth scope: `api:read`.",
+        "x-sim-operation": "billing.status.read",
+        "x-oauth-scope": "api:read",
         "tags": ["Billing"],
         "parameters": [
           {
@@ -105,7 +107,9 @@
       "get": {
         "operationId": "listBillingLogs",
         "summary": "List Billing Logs",
-        "description": "List the credit-denominated billing ledger with source filtering and opaque cursor pagination. `period` defaults to `30d`, so an unqualified request covers only the last 30 days: paginating to `nextCursor: null` exhausts that window, not the whole ledger. An inverted custom window is a 400 rather than an empty page.",
+        "description": "List the credit-denominated billing ledger with source filtering and opaque cursor pagination. `period` defaults to `30d`, so an unqualified request covers only the last 30 days: paginating to `nextCursor: null` exhausts that window, not the whole ledger. An inverted custom window is a 400 rather than an empty page.\n\nOAuth scope: `api:read`.",
+        "x-sim-operation": "billing.logs.list",
+        "x-oauth-scope": "api:read",
         "tags": ["Billing"],
         "parameters": [
           {
@@ -262,7 +266,7 @@
         "type": "http",
         "scheme": "bearer",
         "bearerFormat": "OAuth 2.0 access token",
-        "description": "A Sim OAuth access token obtained by a registered client through the authorization-code flow. The token must carry the scope required by the operation."
+        "description": "A Sim OAuth access token obtained by a registered client through the authorization-code flow. Each operation declares its required scope: api:read permits reads and searches; api:write also permits changes and execution and implies api:read. Scope requirements follow the application operation, independent of HTTP method or workspace role."
       }
     },
     "headers": {