> ## Documentation Index
> Fetch the complete documentation index at: https://hexelstudio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Organizations

> The three-level hierarchy that scopes and isolates all Hexel Studio resources.

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

<Steps>
  <Step title="Organization">
    Your company or team. Contains all users, billing, and workspaces. Fully isolated from other organizations.
  </Step>

  <Step title="Workspace">
    A project or team within the organization. Separates products, teams, or use cases.
  </Step>

  <Step title="Environment">
    An isolated context within a workspace (e.g., production, staging, development). Each has its own agents, instances, knowledge, and credentials.
  </Step>
</Steps>

## 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.

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

## 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.

```python theme={"dark"}
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.          |

## Related pages

<CardGroup cols={2}>
  <Card title="IAM Overview" icon="shield-halved" href="/docs/iam/overview">
    Members, roles, and access control.
  </Card>

  <Card title="Environments" icon="layer-group" href="/docs/iam/environments">
    Manage isolated contexts.
  </Card>

  <Card title="API Keys" icon="key" href="/docs/iam/api-keys">
    Create and scope credentials.
  </Card>

  <Card title="Authentication" icon="lock" href="/docs/getting-started/authentication">
    How scoping is applied at request time.
  </Card>
</CardGroup>

## Next steps

Explore the products: [Compute](/docs/compute/overview), [Data Platform](/docs/data-platform/overview), [Orchestration](/docs/orchestration/overview), and [Tool Gateway](/docs/tool-gateway/overview).