# Workspace

A Workspace is the top-level container for everything you build and manage on the platform. It holds your agents, team members, integrations, media, and knowledge bases. Every action your team takes, from creating and deploying an agent to configuring an SSO provider, happens within a Workspace.

<div data-with-frame="true"><figure><img src="/files/TAGPBqccr2f1QZihhKyb" alt=""><figcaption></figcaption></figure></div>

### How Workspaces Are Structured

A single user account can own or belong to multiple Workspaces, and each Workspace can host multiple users and agents. This makes it easy to separate concerns: maintain per-client Workspaces or give different departments their own isolated environments.

```mermaid
flowchart TD
    U1["👤 User A"] --- W1["🏢 Workspace 1"]
    U1 --- W2["🏢 Workspace 2"]
    U2["👤 User B"] --- W1
    U2 --- W2
    U3["👤 User C"] --- W2

    W1 --- A1["🤖 Agent 1"]
    W1 --- A2["🤖 Agent 2"]
    W2 --- A3["🤖 Agent 3"]
    W2 --- A4["🤖 Agent 4"]
    W2 --- A5["🤖 Agent 5"]

    style W1 fill:#eeedfc,stroke:#615DEC,color:#1a1a2e
    style W2 fill:#eeedfc,stroke:#615DEC,color:#1a1a2e
    style U1 fill:#f0f4ff,stroke:#94a3b8,color:#1a1a2e
    style U2 fill:#f0f4ff,stroke:#94a3b8,color:#1a1a2e
    style U3 fill:#f0f4ff,stroke:#94a3b8,color:#1a1a2e
    style A1 fill:#f0fdf4,stroke:#86efac,color:#1a1a2e
    style A2 fill:#f0fdf4,stroke:#86efac,color:#1a1a2e
    style A3 fill:#f0fdf4,stroke:#86efac,color:#1a1a2e
    style A4 fill:#f0fdf4,stroke:#86efac,color:#1a1a2e
    style A5 fill:#f0fdf4,stroke:#86efac,color:#1a1a2e
```

{% hint style="success" %}
Each Workspace operates independently. Users, agents, integrations, settings, and data do not cross Workspace boundaries.
{% endhint %}

### Switching and Creating Workspaces

The Workspace selector shows which Workspace you are currently in. Open it to search through your Workspaces, switch between them, or create a new one.

<div data-with-frame="true"><figure><img src="/files/NSTtfq0hej5QOYFXLAK8" alt="" width="275"><figcaption></figcaption></figure></div>

{% columns %}
{% column %}

#### <i class="fa-arrow-right-arrow-left">:arrow-right-arrow-left:</i>  Switch Workspace

Open the Workspace selector and pick any Workspace from the list. The list includes every Workspace you own and every Workspace you have been invited to. Use the search field to filter by name.
{% endcolumn %}

{% column %}

#### <i class="fa-plus-large">:plus-large:</i>  Create a New Workspace

Select **Create New Workspace.** Give it a descriptive name that reflects its purpose and choose a timezone and data retention period. Once created, you can start [configuring it](/administration/workspace.md#configuring-your-workspace), [inviting users](/administration/users-and-roles.md) and [adding integrations](/administration/integrations.md).
{% endcolumn %}
{% endcolumns %}

### The Dashboard

The first thing you see when you open Workspace is the Overview dashboard. It gives you a snapshot of activity across all your agents without needing to dig into individual sessions or analytics.

<div data-with-frame="true"><figure><img src="/files/B0eukAq9uk4b7ImlaZJj" alt=""><figcaption></figcaption></figure></div>

The dashboard surfaces three metrics for the last 30 days:

<details>

<summary><strong>Most Used Agents</strong></summary>

Your agents ranked by activity, with user and session counts for the period. Spot which agents are gaining traction and which are declining. Select **View All** to jump to the full [Agents list](/build/agents.md#accessing-an-agent).

</details>

<details>

<summary><strong>Sessions</strong></summary>

Total conversation count across all agents with a percentage change from the previous 30-day window. The line chart shows daily volume so you can spot traffic spikes or drops at a glance.

</details>

<details>

<summary><strong>Users</strong></summary>

Total unique users who interacted with your agents, broken down into new and returning. The trend percentage and chart help you track audience growth over time.

</details>

{% hint style="info" %}
The stats period and timezone are displayed at the bottom of the dashboard. The timezone reflects your Workspace configuration, not your browser.
{% endhint %}

### Navigating the Workspace

The sidebar gives you access to every management feature in your Workspace. Select any of the sections below to explore in detail.

<table data-column-title-hidden data-view="cards"><thead><tr><th>Title</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><h4><i class="fa-robot">:robot:</i></h4><h4>Agents</h4></td><td><a href="/pages/4PxbKJptaV88dlo1EmZp">/pages/4PxbKJptaV88dlo1EmZp</a></td></tr><tr><td><h4><i class="fa-user-group">:user-group:</i></h4><h4>Users</h4></td><td><a href="/pages/kxnr1ajS9Gjq7Jw7PGFP">/pages/kxnr1ajS9Gjq7Jw7PGFP</a></td></tr><tr><td><h4><i class="fa-plug">:plug:</i></h4><h4>Integrations</h4></td><td><a href="/pages/OtcDYSj75LLHNgHnB5mz">/pages/OtcDYSj75LLHNgHnB5mz</a></td></tr><tr><td><h4><i class="fa-images">:images:</i></h4><h4>Media Manager</h4></td><td><a href="/pages/mExM5BPcJlt3bssL0YzI">/pages/mExM5BPcJlt3bssL0YzI</a></td></tr><tr><td><h4><i class="fa-book-blank">:book-blank:</i></h4><h4>Knowledge Bases</h4></td><td><a href="/pages/laj7O1TuLIvlsKlGb5wO">/pages/laj7O1TuLIvlsKlGb5wO</a></td></tr><tr><td><h4><i class="fa-list">:list:</i></h4><h4>Audit Logs</h4></td><td><a href="/pages/SVpjoCEZQ7RBZrQLnjCN">/pages/SVpjoCEZQ7RBZrQLnjCN</a></td></tr></tbody></table>

### Configuring your Workspace

Go to **Workspace > Settings > Configuration** to manage the core properties of your Workspace. Changes here affect every user and agent in the organization.

| Setting                    | What it controls                                                           | Notes                                                    |
| -------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------- |
| **Workspace Name**         | Display name in the sidebar, login page, and all Workspace references      | Use a descriptive name if you manage multiple Workspaces |
| **Timezone**               | Default timezone for dashboard metrics, audit logs, and session timestamps | Does not retroactively adjust existing records           |
| **Data Retention**         | How long conversation data and session logs are stored                     | Options range from 1 to 24 months                        |
| **Workspace Image**        | Logo or avatar shown on the login page and Workspace switcher              | Helps differentiate between Workspaces at a glance       |
| **External Organizations** | Connect your Workspace with external organizations to share resources      | Select **Add Organization** to link a new one            |

### Login Settings

Go to **Workspace > Settings > Login Settings** to control how your team members sign in. Two concerns live here: what the login page looks like, and how authentication works.

#### Login Experience

Customize what users see on the login screen. These settings only apply to the Workspace login page (`https://console.helvia.ai/login?orgId={{your-workspace-id}}`), which you can copy from the **Login URL** field.

| Setting                 | What it controls                                                                      |
| ----------------------- | ------------------------------------------------------------------------------------- |
| **Show Workspace Name** | Displays your Workspace name on the login page                                        |
| **Show Workspace Logo** | Displays the image uploaded in Configuration                                          |
| **Show Custom Message** | Adds a text message below the logo (e.g., a welcome note or internal policy reminder) |
| **Welcome Email**       | Toggle whether new users receive a welcome email after their account is created       |

{% hint style="success" %}
Use **Preview Example** to see how the page looks with your current settings before saving
{% endhint %}

#### Authentication

Three sign-in methods are available. You can enable any combination depending on how your team manages credentials:

* **Email and password:** The default method. Every invited user can sign in with their email and a password they set.
* **Google or Microsoft SSO:** Enable one or both so team members sign in with their existing corporate accounts.
* **Custom SSO:** Connect any OpenID-compatible identity provider by adding an OpenID SSO integration in **Workspace > Integrations**. Select **Add SSO** in Login Settings to link it.

<details>

<summary><strong>Advanced: Post Authentication and Role Mapping</strong></summary>

For advanced workflows, enable the Post Authentication URL to call an external endpoint after login. The platform sends the authentication token to your endpoint, which returns user information for automatic role assignment.

Configure the endpoint **URL**, add any custom **Headers** your service requires, then connect response values to Workspace roles via **Add Value - Role** in **Mapping**

</details>

### Deleting a Workspace

The Danger Zone at the bottom of the Configuration page lets you permanently delete the Workspace. This removes all agents, data, settings, and integrations. Users are not deleted from the platform but lose access to this specific Workspace.

{% hint style="danger" %}
**Permanent Action** Workspace deletion cannot be undone. Ensure you have exported or backed up any necessary data including agents and sessions before proceeding.
{% endhint %}

### Best Practices

* **Name Workspaces descriptively:** If your organization uses multiple Workspaces (e.g., per-client), include the purpose in the name so team members switch to the right one
* **Set the timezone early:** Dashboard stats, audit logs, and session timestamps all inherit this setting. Changing it later does not retroactively adjust existing records
* **Match data retention to compliance needs:** Shorter windows save storage but limit your ability to review historical sessions. Align the setting with your organization's data retention policy
* **Restrict login to SSO when possible:** Centralizing authentication through your identity provider reduces password-related support requests and improves security
* **Review the dashboard weekly:** The 30-day trends on the Overview surface usage shifts early, before they become problems

{% hint style="success" %}
You now understand what a Workspace is, how to configure its core settings, and how to customize the login experience for your team.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.helvia.ai/administration/workspace.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.