Skip to main content

Documentation Index

Fetch the complete documentation index at: https://langwatch.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

LangWatch organizes everything around three workspace scopes. Every Virtual Key, every Routing Policy, every Budget, every Audit Log row, every spend chart attaches to one of:
  • Personal: you. One Personal Workspace per user per org. Your Personal Virtual Keys, your /me dashboard, your spend ledger.
  • Team: a group of people in the same org. Shared budget envelope, shared routing policy override, shared Audit Log scope.
  • Project: a shared application. The right home for a virtual key bundled into an app’s config (a chatbot, an internal RAG, a workflow). One project, many apps if useful, governed centrally.
Every workspace lives inside an organization. Think of the org as the tenant boundary; the three workspaces are the inner partitions.
Pairs with: Members & invites (who lives in your org) and Routing policies (the shape every workspace’s gateway behaviour inherits).

​
When to pick which

Choose by what the artifact is for, not what’s convenient.
You want to…Pick this scopeWhy
Use Claude Code on your laptopPersonalThe CLI persona is per-user; spend, budget, and the Recent activity ledger should be yours.
Mint a key for a chatbot the marketing team ownsProjectThe key outlives any one engineer; project scope decouples the app from a specific person’s account.
Apply a tighter routing policy to the engineering team onlyTeamThe team scope nests under org and overrides the org default for its members.
Cap spend across “everyone in the org”OrganizationOrg scope sits above the three workspaces, see Org-wide budgets.
Cap spend “for marketing only”TeamSame shape as the org cap, narrower scope.
Cap spend for one engineer who’s been making noisePrincipalA Personal workspace’s owner is the principal, pin a budget there.
The chrome’s Workspace Switcher shows you the workspaces you can see; the admin catalog at /settings/governance/tool-catalog controls which ones developers see entries for.

​
Personal Workspace

A Personal Workspace is created automatically the first time you visit a project page in an organization (lazy-ensure on first request). It’s:
  • Owned by you (isPersonal=true, ownerUserId=<your user>).
  • Scoped to one team, your private team, also flagged isPersonal.
  • Only ever has one project, your Personal Workspace project.
  • The home for every Personal Virtual Key you mint via langwatch login or the /me portal.
What you do here:
  • Use the CLI (langwatch claude, langwatch codex, langwatch gemini, etc.), every request flows through your Personal VK and lands in your personal ledger.
  • Issue Personal Virtual Keys for inline app development (the model-provider tiles on /me).
  • Read your own spend, budget, request count, and Recent activity at /me.
What you can’t do:
  • Invite other people into your Personal Workspace. It’s not shared by design.
  • Create additional projects under it. The project count is locked at 1.
  • See another user’s Personal Workspace. The picker, the workspace switcher, the audit log filter, and the team list all strip other users’ personal teams from non-admin viewers (see Personal-workspace privacy).

​
Personal-workspace privacy

By default, other users’ Personal Workspaces are invisible to you: even when you’re the org admin in some structural sense. The privacy contract is enforced at four layers:
  1. Picker procedures (team.getTeamsWithMembers, team.getTeamWithMembers, organization.getOrganizationWithMembersAndTheirTeams) strip personal teams owned by other users from the result, AND null-redact other members’ email addresses while preserving the caller’s own email.
  2. Workspace data (useWorkspaceData hook) fail-closes on null ownerUserId, an orphaned personal team without a clear owner is hidden from everyone.
  3. Audit log Project filter dropdown disambiguates same-name personal workspaces with a parent-team suffix (Personal Workspace · Alice's Workspace, Personal Workspace · Bob's Workspace).
  4. NOT_FOUND on existence probes: team.getTeamWithMembers with another user’s personal-team slug returns NOT_FOUND for non-admins so existence itself isn’t observable.
Org admins still see every Personal Workspace in admin-only surfaces (the audit log, the gateway/budgets list, the org members table), privacy is a non-admin restriction, not an admin one.

​
Team

Teams are groups of people. They:
  • Have one or many human members, each with a per-team role (Admin, Member, Viewer).
  • Contain one or many projects. A project belongs to exactly one team.
  • Inherit the org’s default Routing Policy unless a team-scoped policy overrides it.
  • Carry their own audit log scope, budgets, and tool-catalog entries when admin-scoped to the team.
Create a team at /settings/teams (admin-only). Add members from the existing org member list, invites you make from within the team flow have a Team Assignment block in the same drawer documented at Members & invites. Teams scope down what an aiTools:view permission shows on /me. A team-scoped tile catalog entry appears only for members of that team; an org-scoped tile catalog entry appears for everyone. When a team-scoped entry shares a slug with an org-scoped entry, the team override wins for members of that team, the recommended pattern for “engineering gets Cursor, everyone else gets Copilot.”

​
Project

Projects are shared applications. They:
  • Hold many virtual keys (a project key can be split across multiple deployments, staging, prod, a region).
  • Inherit team-level then org-level routing policies (or override with a project-scoped policy).
  • Are the home for any virtual key that should outlive a single person.
  • Are the right scope for production workloads, customer-facing chatbots, internal RAG agents.
Create a project at /[team]/projects or via the project drawer in the chrome. Project visibility follows the team’s member list, every member of a team can see every project under that team. If you need finer per-project access control, lift the gate to a custom RBAC role instead of nesting projects. When the AI Tools Portal’s model-provider tiles offer to mint a virtual key, the inline form includes a hint: “Building an application for your team? Consider creating a project instead.”: the Personal VK path is fast for personal work but the wrong shape for “everyone on the team uses this key.”

​
Workspace switcher

The header of every authenticated page hosts a single Workspace Switcher dropdown. Across the entire /me chrome and the project chrome, it’s the same component, the only thing that changes is what’s currently selected:
  • On /me and /me/*, the switcher shows My Workspace (your Personal scope).
  • On /[project]/*, it shows the current project name.
  • On /settings/* and /governance, it shows the current admin scope (org or “Choose workspace” if not bound).
Click it to expand a tree:
  • My Workspace (top, your Personal scope, always visible to you).
  • One section per organization you belong to, showing the teams + projects in that org you can see. Section headers disambiguate when two orgs share a name (Acme Inc., Acme Inc. · acme-eu).
  • Other users’ Personal Workspaces are filtered out for non-admins (see Personal-workspace privacy above).
  • Two same-named projects in the same scope get a parent-team suffix to keep them distinguishable.
Changing the workspace updates the URL to the corresponding scope and the chrome continues to show the same switcher with the new selection, it’s not a modal, it’s the chrome’s persistent navigation.

​
How budgets attach to workspaces

The gateway’s Budget shape has 4 scopes (plus a 5th for virtual keys directly):
  • Organization, caps all spend across the org. Set this first.
  • Team, caps spend for a specific team. Multiple team budgets can coexist.
  • Project, caps spend for a specific project. Multiple project budgets per project (different windows, different breach actions) are allowed.
  • Principal, caps spend for a specific human (the owner of a Personal Workspace).
  • VirtualKey, caps spend on a single VK. Configured from the VK’s detail page.
Budgets are evaluated in scope order, broadest first. A request that would breach a Team budget is rejected before a Project budget even gets a turn. The widest applicable budget always wins on Block; on Warn, the response carries the warn header for every breached scope.

​
How routing policies attach to workspaces

Routing Policies live at /settings/routing-policies (org-scoped). One policy is marked default and is the policy every Personal VK binds to on first sign-in. Workspace overrides:
  • Team scope: a team can publish a policy override that applies to every key minted within that team’s projects.
  • Project scope: a project can publish its own policy that overrides the team’s.
  • Personal: Personal VKs always bind to the org default unless an admin attaches a different policy via the AI Tools Portal’s model-provider tile (config.suggestedRoutingPolicyId).
A virtual key’s effective policy is the deepest applicable: VK > Project > Team > Org default.

​
Where to next