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

# Workspaces

> Understand Essal Workspaces — the top-level container for all apps, members, billing, and configuration.

A **Workspace** is the root-level organisational unit in Essal. Every resource in the platform — documents, contacts, users, projects, policies — belongs to a workspace. Your workspace settings, billing plan, and app configuration are all managed at this level.

## Workspace Structure

When you sign up for Essal, you create a workspace with a unique slug (e.g. `acme-corp`). This slug appears in all API requests and forms the namespace for your data:

```
https://api.essal.cloud/v1/
  └── workspaces/
        └── acme-corp/
              ├── office/
              ├── access/
              ├── sales/
              ├── careers/
              ├── project/
              └── guard/
```

Each of the six apps operates within the workspace but maintains its own data namespace and permission scope.

## Workspace Settings

Workspace-level settings control cross-app behaviour:

| Setting             | Description                                        |
| ------------------- | -------------------------------------------------- |
| **Slug**            | Unique identifier used in API paths and admin URLs |
| **Display Name**    | Human-readable name shown in the dashboard         |
| **Default Locale**  | Language and date format applied across all apps   |
| **Allowed Domains** | Email domains permitted to join the workspace      |
| **Billing Plan**    | Determines feature limits and API quotas           |
| **Audit Retention** | How long Guard stores audit log entries            |

## Members and Invitations

Workspace members are users who have been granted access to at least one app. Membership is managed via the Essal Access app or the API:

```bash theme={null}
POST /v1/access/users
{
  "email": "jane.doe@example.com",
  "display_name": "Jane Doe",
  "roles": ["office:editor", "project:viewer"]
}
```

<Note>
  A user can belong to multiple workspaces. Their identity is shared but their roles and permissions are workspace-scoped.
</Note>

## Multi-Workspace Organisations

Enterprise accounts can create multiple workspaces (e.g. one per business unit or region) and link them under a parent Organisation. Linked workspaces share a billing account and can optionally share an identity provider configured in Access.

## Workspace API Object

```json theme={null}
{
  "id": "ws_01HXYZABC",
  "slug": "acme-corp",
  "display_name": "Acme Corp",
  "plan": "enterprise",
  "created_at": "2025-01-15T08:00:00Z",
  "member_count": 142,
  "apps_enabled": ["office", "access", "sales", "careers", "project", "guard"]
}
```