Workspaces & Organizations

Bolti has a two-level resource model:

Organization (your account, billing unit)
└── Workspace (project, environment, or client)
    ├── Agents
    ├── Phone numbers
    ├── Tools
    ├── Contacts
    └── Call logs

If you're a solo developer, you'll probably use one organization with one workspace and never think about this again. If you're an agency, an enterprise team, or anyone who needs separation between projects or environments, this page explains how to model that cleanly.

The two levels

Organization

The organization is your account. Think of it as your company. It owns:

• Billing — credit balance, plan tier (free / starter / growth / enterprise), payment methods, and invoices.
• Members — every person who has access to anything inside the org.
• Workspaces — one or more, depending on how you organize your work.
• Org-level settings — name, slug, logo, and account-wide preferences.

You can belong to multiple organizations (e.g. your own company and a client's company that invited you), and you switch between them in the dashboard.

Workspace

A workspace is a project space inside an organization. It's where your actual work lives:

• Agents you've created
• Phone numbers assigned to those agents
• Tools the agents can call (HTTP and built-in)
• Contacts for outbound calling
• Call logs and recordings from past conversations
• Knowledge bases the agents reference

Resources are fully scoped to one workspace. An agent in workspace A cannot call a tool in workspace B. A phone number bought in workspace A cannot be assigned to an agent in workspace B. This is intentional — it's how Bolti gives you clean isolation.

Every organization has at least one workspace. The first one is created automatically when you sign up.

Roles & permissions

Bolti has roles at both levels. Org roles control who can do account-wide things (billing, member management). Workspace roles control who can do project-level things (build agents, see logs).

Organization roles

Role	What they can do
Owner	Everything. Manage billing, members, workspaces, transfer ownership, delete the org. There's exactly one owner per org.
Admin	Everything except changing billing details and transferring ownership.
Billing	View and manage billing — invoices, payment methods, credit top-ups. No access to agents or settings.
Member	Default role. Can be added to specific workspaces with a workspace role. Has no org-level powers.

Workspace roles

Role	Agents	Conversations & analytics	Workspace settings	Members
Admin	Create / read / update / delete	Read	Update	Manage
Editor	Create / read / update	Read	—	—
Viewer	Read only	Read	—	—

A user's effective permissions in a workspace are: their workspace role's defaults, optionally overridden by per-user permission grants (a JSON map of fine-grained capability flags). Most teams won't need overrides — the role defaults are designed to cover the common cases.

Org role vs workspace role

Org roles don't automatically give you workspace access. Even an Org Admin has to be added to a workspace as a member (typically as workspace Admin) to act inside it. The exception is the Owner, who effectively has access to everything in the org.

Switching between workspaces and orgs

The header in the dashboard has a workspace switcher — a dropdown showing every workspace you have access to in the current organization. Selecting a workspace immediately re-scopes the entire dashboard (agents list, phone numbers, tools, logs, etc.) to that workspace.

If you belong to multiple organizations, you'll see an organization switcher alongside it. Switching org also switches you into that org's first available workspace.

The currently active workspace is also baked into every API request you make — see API Reference → Authentication for the header your client should send.

When to use multiple workspaces

Most accounts start with a single workspace. Add more when one of these patterns applies:

Per-environment (recommended for production teams)

Acme Corp (org)
├── production
└── staging

Build and break things in staging. Promote agent configurations to production when you're confident. Phone numbers, tools, and call logs stay separate, so a staging agent can't accidentally call a real customer.

Per-client (typical for agencies)

Voice Studio (org)
├── client-acme
├── client-globex
└── internal

Each client gets a workspace. Their phone numbers, contacts, and recordings live there. You can give a client's team Viewer access to their workspace without exposing other clients.

Per-product or per-team (typical for larger companies)

Globex Inc (org)
├── support-bot
├── outbound-sales
└── recruiting

Different internal teams own different workspaces. Each team's logs, tools, and metrics stay scoped to their workspace.

Per-region (for geographic separation)

Globex Inc (org)
├── us-east
└── india

Mostly useful when you want phone numbers, recordings, or telephony routing isolated by region.

You can mix these freely — there's no hard limit on the number of workspaces per org.

When not to use multiple workspaces

A common mistake is to make a new workspace for every agent. Don't. Agents already live cleanly side-by-side inside one workspace and share useful resources (tools, phone numbers, contacts).

Multiple workspaces make sense when you want isolation — different members, different phone numbers, different logs. If you're just organizing your own agents, give them clear names and tags inside one workspace.

Settings, slugs, and renames

Both organizations and workspaces have:

• A name — human-readable. Change it any time, and the URL stays the same.
• A slug — short, URL-safe identifier. Defaults to a slugified name on create. You can change it, but old links to the old slug will break.
• A settings object — a JSON blob for org/workspace-level preferences. Most options surface in the UI; advanced flags can also be set via the API.

Within a single org, every workspace must have a unique slug.

Deleting and transferring

• Delete a workspace — deletes all agents, tools, phone numbers, and call logs in it. There's no undo. The workspace's purchased numbers are released. Org admins (and the org owner) can do this.
• Delete an organization — deletes every workspace inside it, plus members, invitations, and historical data. Only the owner can do this. Cancel paid subscriptions first.
• Transfer ownership — the current owner can promote another org member to owner. There can be only one owner at a time, so this is a hand-off, not a clone. Useful when someone leaves the company.

Quick checks

A few rules worth committing to memory:

• One org has many workspaces; one workspace belongs to exactly one org.
• An agent, phone number, or tool never moves between workspaces — recreate it if you need it elsewhere.
• A user can be in many orgs and many workspaces; their effective permissions are the workspace role, not the org role.
• The Owner is special — exactly one per org, and only they can transfer ownership or delete the org.
• Slugs are unique within an org; names don't have to be.

Next: get your team in

Now that the model is clear, you're ready to add teammates with the right level of access. Continue with Invite Your Team →.