# Workspaces

The **workspace** is the unit of work in Bird: where domains are verified, API keys are minted, email is sent, and your team has access. The dashboard is workspace-first, and everything you do happens inside one.

Behind the workspace sits an **organization**: light shared plumbing that holds billing and the member list. A new organization starts with one workspace, so the organization rarely needs thinking about. It matters mainly if you add more workspaces later (to separate, say, production from staging): each workspace keeps its own API keys, domains, suppressions, and team, while billing, membership, and IP infrastructure stay shared above them. Adding a workspace is an owner operation, and once you can open more than one, the profile menu (your avatar in the top bar) lists them so you can switch.

## What's scoped where

| Level        | What lives there                                                                                                                                               |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Organization | [Members and invitations](/docs/guides/users-teams-roles), [billing, plan, and the wallet](/docs/guides/billing-and-usage), dedicated IPs and IP pools, region |
| Workspace    | [API keys](/docs/guides/authentication), the team and its roles, sending-domain assignments, emails, suppressions, [webhook endpoints](/docs/guides/webhooks)  |

Two of these placements are worth dwelling on:

- **IP pools are organization-owned.** Dedicated IPs and the pools that group them belong to the organization and are shared by all its workspaces: reputation you warm in one workspace is reputation every workspace benefits from. Workspaces get read-only visibility into the pools; purchasing and pool management are organization-level operations.
- **Isolation is per workspace.** A workspace's API keys, emails, suppressions, and webhooks are invisible to every other workspace. If you add a second workspace, a key minted in staging can never read production sends, and a suppression added in one does not suppress in another. Shared state lives only at the organization level.

## Regions

Every organization is pinned to exactly one region, currently `us1` (United States) or `eu1` (European Union). The region is set when the organization is created and is immutable: all of the organization's workspaces, data, and sending infrastructure live there, and its API traffic goes to that region's host (`https://us1.platform.bird.com`, `https://eu1.platform.bird.com`). The region is baked into every API key prefix (`bk_us1_...`), so requests route themselves; see [Regions](/docs/api/regions).

## How requests resolve their context

Bird's API uses flat routes (`/v1/email/messages`, `/v1/members`) with no organization or workspace segment in the path. The context comes from how the request authenticates:

- **API keys are workspace-locked.** A key belongs to exactly one workspace, which also determines the organization and region. The context is implicit in the credential: no headers are needed, and a key can never reach another workspace's resources. A request carrying a context header that contradicts the key's workspace is rejected as malformed (`400`) rather than silently reinterpreted.
- **Sessions select context explicitly.** A person can belong to many organizations and workspaces, so session-authenticated requests (the dashboard) name their target per request: `X-Organization-Id` on organization-scoped endpoints, `X-Workspace-Id` on workspace-scoped ones. A session without a grant in the named context gets `403`.

The model mirrors reality: machines operate on one workspace implicitly, humans pick their context explicitly. Whether the request is then allowed is a separate question, answered by [roles](/docs/guides/users-teams-roles) for sessions and scopes for keys.

## Deletion

Deleting a workspace or an organization is deliberately hard to do by accident and deliberately recoverable for a while:

- **Lockout is immediate.** The moment a deletion is accepted, the workspace (or the whole organization) is gone from the outside: it disappears from the dashboard, its API keys stop authenticating and are revoked, and sends are rejected.
- **A 7-day grace window follows.** Data and configuration are retained, untouched, for 7 days. A mistaken deletion can be reversed in this window; contact support to restore it. Everything comes back except API keys, which were revoked at lockout and must be re-issued.
- **Then the purge is irreversible.** After the window, cleanup runs asynchronously and reclaims everything: domains, suppressions, webhook endpoints, templates, memberships, data. Nothing can be recovered once the purge begins.

Two guardrails apply on the way in: an organization's **last workspace cannot be deleted** (`409`; delete the organization instead if that is what you mean), and deleting an organization requires the owner role.

## Next steps

- [Authentication & API keys](/docs/guides/authentication): how keys bind to a workspace
- [Users, teams & roles](/docs/guides/users-teams-roles): workspace roles, plus the org roles that manage billing
- [Regions](/docs/api/regions): regional hosts and routing