Lesson 2: The Console, Organizations and Workspaces

Why the workspace matters before you write any code

Every request you send to Claude runs inside exactly one workspace, and that workspace decides three things: which stored resources the request can see, whose budget it draws on, and which rate limit it counts against. If you get the layout wrong, a runaway dev script can eat the throughput your production traffic needs.

The hierarchy is short:

• Organization: the billing entity. It holds the usage tier, the organization-wide rate limits and the monthly spend cap.
• Workspace: a partition inside the organization. It has its own members, keys, stored resources and optional lower limits.

If you know AWS, think of the organization as the payer account and workspaces as lightweight member accounts: one bill, separate blast radii.

A tour of the Console

Sign in at platform.claude.com. These are the pages you will use most:

Playground              -> try models and API parameters in the browser
                           (older articles call it the Workbench)
Usage                   -> token, request and rate-limit charts
Rate limits             -> your tier and per-model limits;
                           a Workspace dropdown for per-workspace limits
Settings > Workspaces   -> create, edit, archive; per-workspace spend limits
Settings > Members      -> invite people, add them to workspaces, set roles
Settings > Billing      -> the organization's own spend limit

The workspace picker sits at the top of the sidebar. Leave Settings before you look for it, and check it before you do anything else. Half of all "where did my file go?" confusion is being in the wrong workspace.

Gotcha: rate limits and spend limits live on different pages. Rate limits are on the Rate limits page (pick the workspace from the dropdown, then Edit next to a model). Spend limits are under Settings > Workspaces (select the workspace, then Spend limits in the panel).

The Default Workspace: what it can and cannot do

Every organization starts with a Default Workspace. It works for a first experiment, but it has hard edges:

• It cannot be renamed, archived or deleted.
• You cannot set rate or spend limits on it. It always runs at the organization's limits.
• It has no member list of its own. Access follows each person's organization role, so anyone whose role allows API access can use it.
• Usage and cost reports show its workspace_id as null, which is easy to misread as "unattributed".

Treat the Default Workspace as a scratchpad. Anything with real traffic or real data belongs in a workspace you created.

You may also see a Claude Code workspace. Anthropic creates it automatically the first time someone signs in to Claude Code with their Console account, to keep that traffic separate. Don't archive it: that disables Claude Code sign-in through Console billing for the whole organization.

Worked example: dev, staging, production

Only organization admins can create workspaces: Settings > Workspaces > Create workspace, then a name and a colour. Here is a layout as a plan (this is a design document, not a file format the platform reads):

organization: acme-support-bot
# Say the org limit for your main model is 2,000,000 input tokens/min.

workspaces:
  dev:
    members: all engineers (Workspace Developer)
    rate_limit: 200,000 input tokens/min   # a looping script can't starve prod
    spend_limit: $200/month                # caps the cost of an experiment
  staging:
    members: engineers (Workspace Developer)
    rate_limit: production-like            # load tests should behave like prod
    spend_limit: $500/month
  production:
    members: two on-call leads (Workspace Admin)
    rate_limit: not set                    # inherits the organization limit
    spend_limit: sized to forecast, with alerts

Three rules make this work:

1. A workspace limit can be lower than the organization's, never higher.
2. If you set nothing, the workspace matches the organization limit.
3. Organization limits always apply, even if workspace limits add up to more. Giving three workspaces 1,000,000 each against a 2,000,000 organization limit does not create 3,000,000 of capacity.

Capping dev also protects the other workspaces, because what dev can't use stays available to production.

Trade-off: archiving a workspace cannot be undone and archives every API key created for it. Name workspaces carefully ("Prod - Support Bot", not "test2") so you never need to. An organization gets 100 workspaces by default; archived ones don't count.

Roles in one table

People have an organization role and, separately, a role in each workspace.

Inheritance is where people trip up. Organization admins are Workspace Admin everywhere, and organization billing members get Workspace Billing everywhere. Organization users and developers get nothing automatically: an admin must add them on the Members page with Add to workspace. That is how you keep most engineers out of production.

What is scoped to a workspace, and why tenants care

Three kinds of stored resource belong to the workspace they were created in:

• Files uploaded through the Files API
• Message Batches
• Skills

Prompt caches are also isolated per workspace on the Claude API. Workspaces themselves and organization members are managed at the organization level.

The consequence: a file is visible to the whole workspace, not to one end user or conversation. Any key with access to the workspace can reference any file in it. If customer A's and customer B's documents share a workspace, only your application code keeps them apart.

You have two defences:

• Always: treat file IDs as server-side references. Never accept one from an end user. Keep the user-to-file mapping in your own database.
• For hard isolation: give each tenant their own workspace. The boundary is then enforced by the platform rather than by your code. The 100-workspace default means this suits tens of large tenants, not thousands of small ones, unless your account team raises the limit.

Key takeaways

• Every request runs in exactly one workspace, which sets resource visibility, spend and rate limits.
• The Default Workspace cannot be renamed, archived, deleted or given limits. Use it as a scratchpad only.
• Workspace limits can only go below organization limits, and organization limits always win.
• Rate limits are set on the Rate limits page; spend limits under Settings > Workspaces.
• Organization admins and billing members inherit access everywhere; users and developers must be added per workspace.
• Files, Message Batches and Skills are workspace-scoped, so the workspace is your isolation boundary for environments and tenants.