TestSprite · zeshi-du · Aug 13, 2026
@@ -1,11 +1,31 @@
 ---
 title: "Key Terms"
-description: "Core CLI concepts — projects, tests, runs, statuses, credits, scopes, and failure bundles — all in one place."
+description: "Core CLI concepts — workspaces, API keys, projects, tests, runs, statuses, credits, scopes, and failure bundles — all in one place."
 icon: "square-code"
 ---
 
 This page defines the building blocks you'll see across every `testsprite` command. If a term in the docs feels unfamiliar, this is the place to land.
 
+## Workspace
+
+Every user has a **personal workspace**, and can belong to one or more **shared workspaces**. Every project, test, and API key belongs to exactly one workspace — whichever one is active when it's created.
+
+<Tabs>
+  <Tab title="What a workspace is">
+    - A **personal workspace** is created automatically for you; work here draws on your personal balance.
+    - A **shared workspace** holds work that belongs to the workspace itself, visible to every member; work here draws on the workspace's balance instead.
+
+    The CLI doesn't have a "switch workspace" command — which workspace you're acting in is determined entirely by the API key you've configured.
+  </Tab>
+  <Tab title="How the CLI uses it">
+    Every `projectId`, `testId`, and `runId` the CLI returns belongs to the workspace tied to your active API key. To act in a different workspace, configure a key minted from that workspace instead — see [Authentication](/cli/core/authentication) for personal vs. workspace keys.
+  </Tab>
+</Tabs>
+
+<Card title="Workspaces" href="/web-portal/admin/workspaces" icon="users">
+  Personal vs. shared workspaces, members, and roles
+</Card>
+
 ## Project
 
 A **project** is the top-level named container for your tests. Frontend projects target a live public URL; backend projects point at a codebase. Every project has a stable `projectId` you use in most commands.
@@ -168,6 +188,10 @@ Every run is tagged with the surface that triggered it. The **run source** lets
 
 **Credits** are the consumption unit for test execution. The CLI reports your balance via `testsprite usage` and exits non-zero when balance is insufficient.
 
+<Note>
+Which balance `testsprite usage` reports depends on your active API key: a personal key reports your personal balance, a workspace key reports that workspace's balance. See [API Key](#api-key) below.
+</Note>
+
 <Tabs>
   <Tab title="What credits are">
     Key rules:
@@ -192,6 +216,27 @@ Every run is tagged with the surface that triggered it. The **run source** lets
   </Tab>
 </Tabs>
 
+## API Key
+
+The credential the CLI stores in `~/.testsprite/credentials` and sends with every request. Two kinds exist — a **personal key** (`sk-user-...`), the original kind, bound to you; and a **workspace key** (`sk-member-...`), scoped to a specific shared workspace and the only kind mintable today — see [Workspace](#workspace) above for how the two relate.
+
+<Tabs>
+  <Tab title="What an API key is">
+    Every key carries a list of **scopes** (see [Scopes](#scopes) below) regardless of kind. `testsprite setup` verifies whichever key you provide against `GET /me` before storing it.
+  </Tab>
+  <Tab title="How the CLI uses it">
+    ```bash
+    testsprite auth status
+    ```
+
+    Shows the identity and scopes bound to your active key, whichever kind it is.
+  </Tab>
+</Tabs>
+
+<Card title="API Keys" href="/web-portal/admin/api-keys" icon="key">
+  Personal vs. workspace keys — creation, expiry, and revocation
+</Card>
+
 ## Scopes
 
 **Scopes** are permissions that an API key carries. The CLI checks scopes before sending write or run requests, and when access is denied it prints which scope was required and which scopes your key holds. Read commands need read scopes, writes need `write:tests`, and runs need `run:tests`; the purely local `agent install` command needs none, and `setup` works with any valid key.

@@ -152,6 +152,12 @@ API keys carry a list of **scopes** that gate which operations the CLI can perfo
 
 If a command fails with a scope error, the CLI prints the required and granted scopes in both text and JSON modes. You can generate a new key with the needed scopes in the dashboard at <kbd>Settings → API Keys</kbd> → <kbd>Create new key</kbd>.
 
+## Personal vs. workspace keys
+
+The key you configure above can be either kind: a **personal key** (`sk-user-...`) — the original kind, if you already hold one — bound to you and drawing on your personal balance no matter which workspace page you copied it from, or a **workspace key** (`sk-member-...`) — the only kind mintable today — scoped to a specific shared workspace and drawing on that workspace's balance. Either kind works the same way with the CLI — `testsprite setup` doesn't care which one you paste in.
+
+Both kinds are capped: 2 active workspace keys per member per workspace, and 3 active personal keys. So replacing a lost or leaked key isn't always as simple as minting a fresh one — if you're already at the cap, revoke one first.
+
 <Card title="API Keys" href="/web-portal/admin/api-keys" icon="key">
   The Web Portal key management walkthrough
 </Card>

@@ -23,9 +23,9 @@ Before installing, make sure you have:
     The CLI requires **20.19+**, **22.13+**, or **24+** — the odd-numbered releases (21.x, 23.x) aren't supported. If your version doesn't fall in one of those ranges, download a newer release from [nodejs.org <Icon icon="arrow-up-right-from-square" size={12} />](https://nodejs.org/). The CLI also checks the Node version at startup and exits with a clear message if it's too old.
   </Accordion>
   <Accordion title="Where do I get an API key?">
-    Sign in to your TestSprite dashboard, navigate to <kbd>Settings → API Keys</kbd>, and click <kbd>Create new key</kbd>. The key is shown exactly once — copy it before closing the dialog. If you lose it, just create a new one.
+    Sign in to your TestSprite dashboard, navigate to <kbd>Settings → API Keys</kbd>, and click <kbd>Create new key</kbd>. The key is shown exactly once — copy it before closing the dialog. The key you get is a **workspace key** (`sk-member-...`), bound to whichever workspace's page you were on, and capped at 2 active per member per workspace. (TestSprite also has an older **personal key** kind, `sk-user-...` — if you already hold one it keeps working, but new keys are always workspace keys.) If you lose it, revoke it and create a new one — revoke one of the existing keys first if you're already at the cap.
 
-    See [API Keys](/web-portal/admin/api-keys) for the full walkthrough.
+    See [API Keys](/web-portal/admin/api-keys) for the full walkthrough, including personal vs. workspace keys.
   </Accordion>
 </AccordionGroup>
 
@@ -64,7 +64,7 @@ The CLI's source code, releases, and issue tracker live on [GitHub](https://gith
   <img src="../../images/api-key.png" alt="API Keys page with the Create new key button" />
 </Frame>
 
-3. Copy the key — it is shown **once only**. If you lose it, delete the key and create a new one.
+3. Copy the key — it is shown **once only**. If you lose it, revoke it and create a new one. (A workspace key is capped at 2 active per member per workspace — revoke one first if you're already at the limit.)
 
 <Frame>
   <img src="../../images/created-api-key.png" alt="API Key Created dialog with the copy button" />

@@ -12,6 +12,12 @@ The `testsprite` CLI is designed from the ground up for unattended execution:
 - **Stable `--output json`** — every command emits a machine-readable JSON envelope that your pipeline can parse and forward.
 - **Stable exit codes** — exit 0 means the run passed; any non-zero exit lets the shell fail the job. No text scraping required.
 
+<Warning>
+**Your target must be reachable from TestSprite's cloud.** Tests run on TestSprite's cloud runners, so `--target-url` has to be a public `http(s)` address. `localhost`, `127.0.0.1`, `::1`, `0.0.0.0`, link-local, and private (RFC 1918) addresses are **rejected during pre-flight with exit code `5`, before any run is triggered** — so a dev server started inside the CI job cannot be tested directly. This is the most common first-run CI failure.
+
+In CI, point `--target-url` at a **publicly reachable preview, staging, or deploy-preview URL** (for example, the per-pull-request preview URL your hosting provider creates). To test a local app, use the [TestSprite MCP Server](/mcp/getting-started/introduction), which opens a tunnel for you — the CLI itself does not tunnel.
+</Warning>
+
 ## Authenticating in CI
 
 Set your API key as a repository or environment secret. In GitHub, go to <kbd>Settings → Secrets and variables → Actions</kbd> and click <kbd>New repository secret</kbd>:
@@ -67,6 +73,10 @@ testsprite test run test_3a9f21c7 --wait --output json > result.json || \
 
 ## A GitHub Actions workflow
 
+<Note>
+Install and invoke the `testsprite` CLI directly, as the example below does — this is the supported way to run TestSprite in CI, on any platform. If you previously set up an older TestSprite GitHub Action from the marketplace, migrating to the CLI gives you stable exit codes, JUnit output, and a consistent pass/fail verdict.
+</Note>
+
 The example below runs all backend tests in a project on every pull request and fails the job if any test does not pass:
 
 ```yaml

@@ -150,6 +150,7 @@
           {
             "group": "Admin",
             "pages": [
+              "web-portal/admin/workspaces",
               "web-portal/admin/api-keys",
               "web-portal/admin/billing-and-plans"
             ]

@@ -37,6 +37,8 @@ First, you'll need a TestSprite API key for any installation method:
 3. Click **"New API Key"**
 4. **Copy** your API key (you'll need it for installation)
 
+The key you just created is a **workspace key** (`sk-member-...`), bound to whichever workspace's page you were on. TestSprite also has an older **personal key** kind (`sk-user-...`) — if you already hold one it works equally well with the MCP Server. See [API Keys](../../web-portal/admin/api-keys) for the full comparison, including expiry and revocation.
+
 ## Installation
 
 Follow the instructions for your specific client to add the TestSprite MCP server.

@@ -255,14 +255,14 @@ If you experience issues about **Invalid or missing API key**, please follow the
     ```json
     {
       "env": {
-        "API_KEY": "ts_live_abcd1234efgh5678ijkl"
+        "API_KEY": "sk-user-abcd1234efgh5678ijkl"
       }
     }
     ```
   </Step>
 
   <Step title="Verify API key format">
-    - Should start with `sk-user-`
+    - Should start with `sk-user-` (a personal key) or `sk-member-` (a workspace key) — both are equally valid for the MCP Server
     - Should be 32+ characters long
     - No extra spaces or characters
   </Step>

@@ -1,31 +1,55 @@
 ---
-title: "API Keys & MCP Integration"
-description: "Manage your TestSprite API keys in the Web Portal and view test results from MCP Server executions."
+title: "API Keys"
+description: "The two kinds of TestSprite API keys — personal and workspace — what each is bound to, and how to create, expire, and revoke them."
 icon: "key"
 ---
 
-## Generating API Keys
+## Two Kinds of API Keys
 
-Generate API keys for MCP Server integration and other third-party tools.
+An API key authenticates the CLI and the MCP Server as you. Two kinds exist:
 
-<Steps>
-  <Step title="Navigate to Settings">
-    Go to <kbd>Settings > API Keys</kbd> and click <kbd>New API Key</kbd>.
-    <Frame>
+| | Personal key | Workspace key |
+| :--- | :--- | :--- |
+| **Prefix** | `sk-user-` | `sk-member-` |
+| **How you get one** | Not mintable today — this is the original key kind, from before workspace keys existed | Click **New API Key** on any workspace's API Keys page, including your personal workspace's |
+| **Bound to** | You — not to any workspace, so it behaves the same wherever it was created | The workspace whose page minted it |
+| **Where it's listed** | Your personal workspace's API Keys page | That workspace's API Keys page |
+| **Draws on** | Your personal balance | That workspace's balance |
+| **What it creates** | Lands in your personal workspace | Belongs to that workspace |
+| **Active-key cap** | 3 active | 2 active per member, per workspace |
+| **Revoking** | Revokes it everywhere — it was never workspace-scoped | Revokes that key only; you can mint another for the same workspace |
+
+<Note>
+Both kinds are capped, with different limits: 2 active workspace keys per member per workspace (so you can rotate one while the other stays in use), and 3 active personal keys. Going over a cap fails until you revoke one. Revoking is immediate.
+</Note>
+
+<Info>
+Personal keys predate the workspace-key kind and can no longer be minted. If you already have one, it keeps working exactly as before — every key minted today, from any workspace's API Keys page, is a workspace key.
+
+A shared workspace's API Keys page lists only that workspace's keys. Your personal keys are on your personal workspace's page, where you can also revoke them — they're left off a shared workspace's page because anything they create lands in your personal workspace, not in the shared one.
+</Info>
+
+See [Workspaces](../../web-portal/admin/workspaces) for what a workspace is and how personal vs. shared workspaces differ.
+
+## Creating a Key
+
+Every key minted today is a workspace key — there's no separate flow for a personal key. Go to <kbd>Settings > API Keys</kbd> in whichever workspace should own the key and click <kbd>New API Key</kbd>; the key you get back is bound to that workspace, including your personal workspace if that's the page you were on.
+
+<Frame>
   <img src="../../images/api-key.png"  alt="API Key" />
 </Frame>
-  </Step>
-
-  <Step title="Configure and Save">
-    Provide a **descriptive name** (e.g., "MCP Integration"), click <kbd>Create</kbd>, then use the copy icon to copy the generated API key immediately.
-    <Warning>
-      Store it securely. It won't be shown again
-    </Warning>
-    <Frame>
-    <img src="../../images/created-api-key.png"  alt="API Key" />
-    </Frame>
-  </Step>
-</Steps>
+
+Provide a **descriptive name** (e.g., "MCP Integration") and optionally set an expiration. Leave it blank and the key does not expire — unless the workspace enforces a maximum lifetime, in which case a longer expiry you request is rejected, and a key created without one is issued with that maximum instead. Click <kbd>Create</kbd>, then use the copy icon to copy the generated key immediately.
+
+<Warning>
+  Store it securely. It won't be shown again.
+</Warning>
+
+<Frame>
+<img src="../../images/created-api-key.png"  alt="API Key" />
+</Frame>
+
+The key is stored hashed; its full value is shown exactly once, at creation, and never again.
 
 ## Managing API Keys
 
@@ -40,8 +64,9 @@ Generate API keys for MCP Server integration and other third-party tools.
 | Field | Description |
 | :--- | :--- |
 | <kbd>Name</kbd> | Descriptive identifier |
-| <kbd>API Key</kbd> | Partially hidden (e.g., `sk_test_****...****abcd`) |
+| <kbd>API Key</kbd> | Partially hidden. A personal key shows its first and last few characters (`sk-user-abcde...vwxyz`); a workspace key shows only its leading characters (`sk-member-ab...`), because the rest is never stored in a readable form |
 | <kbd>Created At</kbd> | When generated |
+| <kbd>Expires</kbd> | Optional at creation. If not set, the key does not expire — unless the workspace enforces a maximum lifetime, in which case it's issued with that maximum |
   </Tab>
   <Tab title="Available Actions">
     Manage your API keys with these actions to control access, monitor usage, and maintain security.
@@ -86,6 +111,9 @@ Click on any test result to view **detailed test execution logs**, **individual
 <Info>Your API key is used in the MCP Server configuration to authenticate with TestSprite's testing engine.</Info>
 
 <CardGroup cols={2}>
+  <Card title="Workspaces" href="../../web-portal/admin/workspaces">
+    What a workspace is and how personal vs. shared workspaces differ
+  </Card>
   <Card title="Start Your First Test" href="../../mcp/getting-started/first-test">
     Get hands-on experience with TestSprite MCP
   </Card>

@@ -0,0 +1,55 @@
+---
+title: "Workspaces"
+description: "What a workspace is, how a shared workspace differs from your personal workspace, and where members and credentials fit in."
+icon: "users"
+---
+
+## What a Workspace Is
+
+Everything you do in TestSprite — projects, tests, runs, and API keys — belongs to a **workspace**. Every user has a **personal workspace** automatically, and can also belong to one or more **shared workspaces**.
+
+Whichever workspace is active determines where new work lands: projects you create, tests you generate, and keys you mint all belong to that workspace, not to you individually.
+
+<Note>
+Access inside a workspace is all-members: everyone who belongs to a workspace can see and work with its projects and tests. Roles only gate workspace management itself — things like membership and workspace settings — not day-to-day testing.
+</Note>
+
+## Personal Workspace vs. Shared Workspaces
+
+<Tabs>
+  <Tab title="Personal Workspace">
+    Your personal workspace is created for you automatically and is yours alone — there's no membership to manage. Anything created here draws on your personal balance.
+  </Tab>
+  <Tab title="Shared Workspaces">
+    A shared workspace holds work that belongs to the workspace itself rather than to any one member. Anyone who belongs to it can see and work with its projects and tests, and spend on work created there draws on the workspace's own balance rather than any individual member's.
+  </Tab>
+</Tabs>
+
+## Creating and Switching Workspaces
+
+You can create additional shared workspaces and switch between them and your personal workspace. Whichever workspace is active at the time determines where a new project, test, or API key is created — so it's worth checking which workspace you're in before you start new work.
+
+Workspace management — creating a workspace, inviting or removing members, and changing workspace-level settings — lives under <kbd>Workspace Settings</kbd> in the Settings area.
+
+## Members and Roles
+
+Every member of a shared workspace can see and work with the workspace's projects and tests — there's no per-project access restriction between members. Roles come into play only for managing the workspace itself (for example, membership and workspace settings), not for using it day to day.
+
+## Credentials
+
+Workspaces don't have their own separate concept of a login — what you use to authenticate is an **API key**, and a key can either belong to you personally or be scoped to a specific workspace. For the full breakdown of the two kinds of keys, how they're minted, and which balance each one draws on, see the API Keys page.
+
+<Card title="API Keys" href="/web-portal/admin/api-keys" icon="key">
+  Personal vs. workspace keys, creation, expiry, and revocation
+</Card>
+
+## Where to Go Next
+
+<Columns cols={2}>
+  <Card title="API Keys" href="/web-portal/admin/api-keys" icon="key">
+    Create workspace keys, plus manage any key you already hold
+  </Card>
+  <Card title="Billing and Plans" href="/web-portal/admin/billing-and-plans" icon="credit-card">
+    Plan tiers and monthly credits
+  </Card>
+</Columns>