feat(auth): add scoped OAuth access and browser-based CLI login

.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` | Includes `api:read`, plus 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/content/docs/cli/audit-logs.mdx

@@ -15,7 +15,7 @@ Every command below also accepts the [global options](/cli/commands#global-optio
 sim audit-logs get <auditLogId> [options]
 ```
 
-Get Audit Log (personal API key required)
+Get Audit Log (OAuth login or personal API key required)
 
 **Arguments**
 
@@ -33,7 +33,7 @@ Get Audit Log (personal API key required)
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--organization <value>` | No | Organization ID; defaults to your only organization, and is required when your account belongs to more than one (personal API key required). |
+| `--organization <value>` | No | Organization ID; defaults to your only organization, and is required when your account belongs to more than one (OAuth login or personal API key required). |
 
 </CommandTable>
 
@@ -43,7 +43,7 @@ Get Audit Log (personal API key required)
 sim audit-logs list [options]
 ```
 
-List Audit Logs (personal API key required)
+List Audit Logs (OAuth login or personal API key required)
 
 **Options**
 
@@ -59,8 +59,8 @@ List Audit Logs (personal API key required)
 | `--include-departed` | No | Include actions by users who have left the organization. |
 | `--no-include-departed` | No | Send --include-departed as false. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
-| `--organization <value>` | No | Organization ID; defaults to your only organization, and is required when your account belongs to more than one (personal API key required). |
+| `--organization <value>` | No | Organization ID; defaults to your only organization, and is required when your account belongs to more than one (OAuth login or personal API key required). |
 | `--actor-email <value>` | No | Filter by actor email address. |
-| `--all-workspaces` | No | Do not filter to the configured workspace (personal API key required for account-wide access). |
+| `--all-workspaces` | No | Do not filter to the configured workspace (OAuth login or personal API key required for account-wide access). |
 
 </CommandTable>