> ## Documentation Index
> Fetch the complete documentation index at: https://moonshadow-ep3.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspaces: Organizing Your Team in Moonshadow

> Workspaces are team-level containers in Moonshadow. Each workspace has its own integrations, members, API keys, and automation rules.

A workspace is the central container for everything your team does in Moonshadow. It holds your integrations, members, API keys, and automation rules. Most teams use one workspace per organization, but you can create additional workspaces to separate environments or teams.

## What Is a Workspace?

When you sign up for Moonshadow, you are prompted to create your first workspace. Every API request, integration, and event is scoped to a workspace, so choosing the right structure early keeps your data organized and your API keys isolated.

Each workspace has:

* A unique identifier used in API paths
* Its own set of integrations with external tools
* Members with roles that control access
* API keys for programmatic access
* Automation rules triggered by events

## Creating a Workspace

### Via the Dashboard

1. Log in to Moonshadow and open the workspace selector in the top navigation.
2. Click **Create Workspace**.
3. Enter a name and optionally invite members.
4. Confirm to create the workspace and land on its settings page.

### Via the API

You can also create a workspace programmatically. Pass your Bearer token in the `Authorization` header.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.moonshadow.dev/v1/workspaces \
    -H "Authorization: Bearer <API_KEY>" \
    -H "Content-Type: application/json" \
    -d '{"name": "Engineering Team"}'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.moonshadow.dev/v1/workspaces",
      headers={
          "Authorization": "Bearer <API_KEY>",
          "Content-Type": "application/json"
      },
      json={"name": "Engineering Team"}
  )
  print(response.json())
  ```
</CodeGroup>

Example response:

```json theme={null}
{
  "id": "ws_9f8a7b6c5d4e3f2a",
  "name": "Engineering Team",
  "created_at": "2024-06-12T14:32:00Z",
  "updated_at": "2024-06-12T14:32:00Z"
}
```

## Listing Your Workspaces

Retrieve all workspaces you have access to with a GET request.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.moonshadow.dev/v1/workspaces \
    -H "Authorization: Bearer <API_KEY>"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.moonshadow.dev/v1/workspaces",
      headers={"Authorization": "Bearer <API_KEY>"}
  )
  print(response.json())
  ```
</CodeGroup>

Example response:

```json theme={null}
{
  "data": [
    {
      "id": "ws_9f8a7b6c5d4e3f2a",
      "name": "Engineering Team",
      "created_at": "2024-06-12T14:32:00Z",
      "updated_at": "2024-06-12T14:32:00Z"
    }
  ],
  "has_more": false
}
```

## Workspace Settings

Open a workspace's settings page from the dashboard to manage:

* **Name and description**: Keep the workspace identifiable for your team.
* **API keys**: Generate and revoke keys for programmatic access.
* **Members**: Invite teammates and assign roles.
* **Billing**: View usage and manage the subscription plan.

## Multiple Workspaces

You can belong to many workspaces and switch between them from the top navigation. This is useful when you want to separate production and staging environments, or when different teams need isolated integrations and members.

<Note>
  API keys are scoped to a single workspace. Requests made with one workspace's key cannot access resources in another workspace.
</Note>

## Members and Roles

Every workspace has members, and each member has a role that determines what they can do. Roles range from full administrative access to read-only viewing.

| Role   | Description                                                                     |
| ------ | ------------------------------------------------------------------------------- |
| Owner  | Full control over the workspace, billing, and members.                          |
| Admin  | Can manage integrations, members, and automations. Cannot delete the workspace. |
| Member | Can create automations and view data. Cannot manage billing or invite users.    |
| Viewer | Read-only access to dashboards and events.                                      |

For a detailed breakdown of each permission, see [Permissions and Roles](/concepts/permissions).