Organizations - Hexel Studio

Hexel Studio uses a three-level hierarchy to organize and isolate resources: organization → workspace → environment. Every resource lives in an environment, and your credentials determine which scope you operate in.

The hierarchy

Organization

Your company or team. Contains all users, billing, and workspaces. Fully isolated from other organizations.

Workspace

A project or team within the organization. Separates products, teams, or use cases.

Environment

An isolated context within a workspace (e.g., production, staging, development). Each has its own agents, instances, knowledge, and credentials.

Resource scoping

Resource	Scoped to	Notes
Users, roles, policies	Organization
Service accounts, API keys	Workspace + Environment
Agents, instances, sandboxes	Environment	Runtime resources — fully isolated per environment.
Knowledge stores, memory, connectors	Workspace / Environment
Fleet definitions, agent registry	Workspace	Shared across environments.
Usage records, audit logs	Organization	Rolled up for billing.

Billing and usage attribution

Usage records (both compute_cpu_second and agent_compute_unit) are tagged with environment_id and workspace_id, then roll up to the organization level for billing. This means:

You can break down cost per workspace and per environment in usage reports.
Invoices are issued at the organization level — one bill per org.
Separate environments give you attribution granularity without requiring separate billing accounts.

Use distinct environments (e.g., team-a-prod, team-b-prod) to isolate billing attribution between teams that share the same organization.

What is shared vs isolated within a workspace

Environments within a workspace share the same fleet definitions and agent registry — you register an agent once and deploy it to any environment. Only runtime resources are isolated per environment:

Shared (workspace-level)	Isolated (per environment)
Fleet configuration	Agent instances
Agent registry entries	Sandboxes
Routing policies	Knowledge store data
	Memory store data
	Credentials

This means promoting an agent from staging to production requires only deploying a new instance in the production environment — no re-registration needed.

Isolation guarantees

Level	Isolation
Organization	Complete; one org cannot access another’s data.
Workspace	Logical; resources are separated within the org.
Environment	Logical; production and development do not interfere.

How scoping works

Your API key or OAuth client is scoped to a specific workspace and environment. Every API call is routed to that context automatically.

from hexel import Hexel

# Credentials determine org, workspace, and environment
client = Hexel(api_key="YOUR_API_KEY")

# Operations are scoped automatically
client.compute.agent.list()  # Agents in this environment only

Recommended structure

Practice	Rationale
One organization per company	Simplifies billing and user management.
One workspace per project or team	Keeps resources organized and access controlled.
Separate environments per stage	Prevents production and development from interfering.
Separate credentials per environment	Limits blast radius if a key is compromised.

IAM Overview

Members, roles, and access control.

Environments

Manage isolated contexts.

API Keys

Create and scope credentials.

Authentication

How scoping is applied at request time.

Next steps

Explore the products: Compute, Data Platform, Orchestration, and Tool Gateway.

​The hierarchy

​Resource scoping

​Billing and usage attribution

​What is shared vs isolated within a workspace

​Isolation guarantees

​How scoping works

​Recommended structure

​Related pages

IAM Overview

Environments

API Keys

Authentication

​Next steps

The hierarchy

Resource scoping

Billing and usage attribution

What is shared vs isolated within a workspace

Isolation guarantees

How scoping works

Recommended structure

Related pages

Next steps