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 — the breadcrumb always names your workspace, and everything you do happens inside it.
Behind the workspace sits an organization — light shared plumbing that holds billing and the member list. Today each customer has 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.
What's scoped where
| Level | What lives there |
|---|---|
| Organization | Members and invitations, billing, plan, and the wallet, dedicated IPs and IP pools, region |
| Workspace | API keys, the team and its roles, sending-domain assignments, emails, suppressions, webhook endpoints |
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.
The full resource surface is in the workspaces reference.
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.
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. If a request carries a context header that contradicts the key's workspace, it is rejected with 403 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 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, access stops: logins are refused, API keys stop authenticating and are revoked, sends are rejected. From the outside, it's gone.
- 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, memberships, data. There is no recovery after 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.
Related
- Authentication & API keys — how keys bind to a workspace
- Users, teams & roles — workspace roles, plus the org roles that manage billing
- Workspaces reference — full endpoint and schema documentation
- Regions — regional hosts and routing