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

# Workspace setup

> Set up your Hightouch workspace: how it's structured, who can access what, and which governance controls your team needs. Each step includes a recommended starting point and when to choose differently.

## Before you begin

* Admin or organization-owner access to your Hightouch account
* Your organization's SSO provider details (if using SSO)
* Your marketing team's first use cases. See the examples for [lifecycle](https://docs.hightouch.com/getting-started/lifecycle.md#plan-your-first-use-cases) and [paid media](https://docs.hightouch.com/getting-started/paid-media.md#plan-your-first-use-cases) teams.

In many companies, a project lead coordinates setup and the IT team owns sign-in, storage, and networking. The steps below are organized by responsibility, so share them with whoever owns each part.

Hightouch's access and governance controls layer on top of each other. You don't need all of them on day one. Each step below covers the decision you're making, a recommended starting point, and when to choose differently. For the full reasoning behind each control, see [Governance best practices](https://docs.hightouch.com/workspace-management/governance.md).

> [!TIP]
>
> **Using only Ad Studio?** Ad Studio doesn't need a warehouse connection. Set up sign-in and access (step 3), then agent access and Context Hub (step 6): give marketers the **Access Agents** grant, connect your ad platforms, and create a brand profile. Your data team doesn't need to set anything up.

## Setup steps

### 1. Learn the building blocks

Before configuring anything, learn [how Hightouch is organized](https://docs.hightouch.com/workspace-management/overview): organizations, workspaces, user groups, roles, environments, and Spaces.

![Workspace design diagram](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/get-started/workspace-diagram.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=66f23aa75361f6e6033b4f1ac3ccf68d)

An **organization** represents your company and holds users, billing, and SSO. **Workspaces** sit inside it, each with its own sources, destinations, models, syncs, and users. Organization roles and workspace roles are separate: an organization admin isn't automatically a workspace admin, and the reverse is also true.

### 2. Decide your workspace structure

**Decide:** whether teams share one workspace or work in separate ones.

| Recommended starting point | Choose differently when |
| - | - |
| One production workspace for all teams. Separate teams inside it with groups, roles, Spaces, and subsets. | You need complete isolation: data residency in another region, separate infrastructure, or business units that must not share data or configuration. |
| Test changes to models and syncs in a linked staging workspace with [environments](https://docs.hightouch.com/workspace-management/environments.md). | You want review on audiences and other Customer Studio changes, or you only need review before changes go live. Use [approval flows](https://docs.hightouch.com/workspace-management/approval-flows.md) instead. |

Then set up your organization and [first workspace](https://docs.hightouch.com/workspace-management/workspaces.md). Choose a region, pick a workspace name and slug, and work through the onboarding checklist. To compare workspaces and environments side by side, see [Do you need another workspace?](https://docs.hightouch.com/workspace-management/workspaces.md#do-you-need-another-workspace)

### 3. Set up sign-in and access

**Decide:** how people sign in, how you group them, and what each group can do.

| Control | Recommended starting point | Choose differently when |
| - | - | - |
| Sign-in | [SAML SSO](https://docs.hightouch.com/workspace-management/sso.md) with SCIM, so accounts and group membership follow your identity provider | You're evaluating Hightouch or have a small team. Invite users by email and add SSO later. |
| User groups | One group per team (for example, Admins, Data, Lifecycle marketing, Paid media), mapped from groups in your identity provider | Regions or brands need different access. Create a group for each. |
| Roles | [Pre-built roles](https://docs.hightouch.com/workspace-management/roles.md#pre-built-roles): Admin for the data or IT team, Editor for marketers, Viewer for stakeholders | A team should only use specific sources, destinations, or products. Create a [custom role](https://docs.hightouch.com/workspace-management/roles.md#custom-roles). |
| Admin access | Keep organization admins to your IT or data platform team, and delegate day-to-day management to workspace admins | You're a small team where one person owns both. |

Assign roles to groups, not individual users. A user in several groups gets the highest access any of their groups grants.

When you roll out SSO:

* Copy the **SSO URL** and **Audience URI** exactly from Hightouch. Small typos cause login loops.
* Plan which identity provider groups map to which Hightouch groups before you turn SSO on.
* Test with two or three users before inviting everyone, and keep an admin signed in on a separate browser session in case you need to fix the setup.

For details, see [SSO rollout best practices](https://docs.hightouch.com/workspace-management/sso.md#rollout-migration-and-diagnostics-best-practices), [Manage users and groups](https://docs.hightouch.com/workspace-management/user-management.md), and [Roles](https://docs.hightouch.com/workspace-management/roles.md). To hand off admin rights when someone leaves, see [Transfer organization admin access](https://docs.hightouch.com/workspace-management/user-management.md#transfer-organization-admin-access).

![User groups diagram](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/get-started/user-group-diagram.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=13c1130d1fbaedf6eee26b52401a68e3)

*User groups manage access across workspaces, with roles assigned at the group level.*

### 4. Choose governance for your team size

**Decide:** which controls your team needs now. Start with the tab that matches your organization, and add controls as you grow.

> [tab] Smaller teams
>
> A few people share one workspace and trust each other's changes.
>
> * Your workspace structure, user groups, and pre-built roles from the previous steps are enough to start.
> * Add [audit logs](https://docs.hightouch.com/workspace-management/audit-logs.md) to your routine so you can see who changed what. They cover 90 days of activity.

> [tab] Growing teams
>
> Several teams share a workspace but work on different regions, brands, or channels.
>
> * [Subsets](https://docs.hightouch.com/customer-studio/subsets.md): Limit the records each team can use, such as one region or brand.
> * [Spaces](https://docs.hightouch.com/workspace-management/spaces.md): Keep each team's audiences and syncs separate while they share models and destinations. Spaces are enabled by Hightouch on request.
> * [Destination rules](https://docs.hightouch.com/customer-studio/destination-rules.md): Enforce consent for each channel, so opted-out customers are filtered out at sync time no matter who built the audience.

> [tab] Larger or regulated teams
>
> Many teams, regions, or business units, or formal review requirements.
>
> * [Custom roles](https://docs.hightouch.com/workspace-management/roles.md#custom-roles) scoped to the sources, destinations, and products each team uses
> * [Subsets](https://docs.hightouch.com/customer-studio/subsets.md) and [Spaces](https://docs.hightouch.com/workspace-management/spaces.md) by region, brand, or business unit
> * [Destination rules](https://docs.hightouch.com/customer-studio/destination-rules.md) for consent and regional policy
> * [Audience and sync templates](https://docs.hightouch.com/customer-studio/templates.md) so new work starts from approved logic, with templates required if needed
> * [Approval flows](https://docs.hightouch.com/workspace-management/approval-flows.md) so changes are reviewed before they go live
> * [Environments](https://docs.hightouch.com/workspace-management/environments.md) for promoting models and syncs from staging to production
> * [Audit logs](https://docs.hightouch.com/workspace-management/audit-logs.md), written to your warehouse with [Warehouse Sync Logs](https://docs.hightouch.com/syncs/warehouse-sync-logs.md) for retention beyond 90 days

Some common situations and the controls that handle them:

| If… | Use |
| - | - |
| Teams share customer data but work independently | One workspace with Spaces and subsets |
| Regions or entities must be fully separate, such as EU data processed only in the EU | Separate regional workspaces, each tied to a regional warehouse |
| Consent rules differ by channel | Destination rules for each destination |
| Sensitive values should be hidden from everyone in the app | [Redacted columns](https://docs.hightouch.com/customer-studio/data-masking.md) |
| Key segments and sync setups should be standardized | Audience and sync templates |
| Changes, such as new paid media syncs, need central approval | Approval flows, with custom roles so contributors draft and approvers publish. Turn on [Prevent self-approval](https://docs.hightouch.com/workspace-management/approval-flows.md#prevent-self-approval) so no one approves their own changes. |

### 5. Secure your infrastructure

**Decide:** where Hightouch stores customer data at rest, and how it reaches your systems.

Set up [self-hosted storage](https://docs.hightouch.com/security/storage.md) so customer data at rest stays in a bucket in your own cloud. It's required on the Business tier, so set it up before your first sync. Adding it later means resyncing existing syncs. Your IT team usually provisions the bucket. Then configure the rest as your security requirements call for:

* [Security overview](https://docs.hightouch.com/security/overview): Encryption, compliance, and hosting details.
* [Networking](https://docs.hightouch.com/security/networking): Tunnels, PrivateLink, and IP allowlisting. Your data team needs this to connect a warehouse in a private network.
* [Warehouse Sync Logs](https://docs.hightouch.com/syncs/warehouse-sync-logs.md): Write sync history to your warehouse.

### 6. Set up agent access and Context Hub

**Decide:** who can use agents, who maintains the context they work from, and which context to add first. This step applies if your team uses Agents, Ad Studio, or Lifecycle Studio.

| Decision | Recommended starting point |
| - | - |
| Who can use agents | Give the **Access Agents** grant to the marketers who use Agents, Ad Studio, or Lifecycle Studio. See [Roles](https://docs.hightouch.com/workspace-management/roles.md#agents). |
| Who can change Context Hub | Give the **Configure Agents** grant only to the people who own context, not to everyone who uses agents. Without it, Context Hub is hidden. Configure Agents only works for people who also have Access Agents. |
| Who owns each area | Platform admins own permissions and workspace configuration. Data teams own business definitions, metrics, and data connections. Marketing and creative teams own brand profiles, assets, and content guidelines. See [Manage Context Hub across your team](https://docs.hightouch.com/context-hub/overview#manage-context-hub-across-your-team). |
| What to add first | The context your first use case needs. For campaign analysis, [connect your ad platforms](https://docs.hightouch.com/context-hub/connections.md) and add a business context file with your metric definitions. For ads or emails, start with a [brand profile](https://docs.hightouch.com/context-hub/brands.md). |

You don't need to configure all of [Context Hub](https://docs.hightouch.com/context-hub/overview) before teams start. Add context for one use case, review what agents produce, and expand from there.

### 7. Prepare Native Delivery (optional)

If your team sends email, SMS, or push from Hightouch with [Native Delivery](https://docs.hightouch.com/native-delivery/overview), work through [Prepare for your first send](https://docs.hightouch.com/native-delivery/overview#prepare-for-your-first-send) with your Hightouch team and your data team before the first campaign.

### 8. Organize resources (optional)

**Decide:** how teams will find their work as the workspace grows.

Set up a [folder structure](https://docs.hightouch.com/workspace-management/folders-filters.md) early, organized by team or region. Only workspace admins can change folders, so agree on the structure before teams start building. Use labels for things folders can't capture, such as campaign type (`type:email`) or brand (`brand:brand-a`). Folders and labels help teams find resources. They don't restrict access.

## Troubleshoot common setup issues

These are the setup questions admins ask most often.

| Problem | What to check |
| - | - |
| Users can sign in with SSO but don't see any workspaces | Confirm the expected groups are sent from your identity provider and mapped to Hightouch groups that have a workspace role. See [SSO diagnostics](https://docs.hightouch.com/workspace-management/sso.md#diagnostics). |
| A marketer can't create or edit traits | Traits need the **Manage traits** grant on the related parent model, or **Configure schema** on the source. See [Roles](https://docs.hightouch.com/workspace-management/roles.md#who-can-manage-traits-on-a-related-or-event-model). |
| A reviewer can't approve changes | Workspace draft editors and viewers can't approve. Give reviewers a different role, or a custom role with approval rights. See [Approval flows](https://docs.hightouch.com/workspace-management/approval-flows.md). |
| Someone can't see Agents, Ad Studio, Lifecycle Studio, or Context Hub | Check their role for the **Access Agents** and **Configure Agents** grants. See [Roles](https://docs.hightouch.com/workspace-management/roles.md#agents). |
| A team can't see another team's audiences or syncs | This is expected when you use Spaces. Add the user's group to the Space if they need access. See [Spaces](https://docs.hightouch.com/workspace-management/spaces.md). |

## Readiness checklist

Before marketers start working, confirm the workspace is ready.

* [ ] Workspace created in the right region
* [ ] SSO tested with a few users before rollout (if you use SSO), and at least one admin can still sign in if something breaks
* [ ] User groups created, with a role assigned to each
* [ ] Governance controls for your team size are in place (step 4)
* [ ] [Self-hosted storage](https://docs.hightouch.com/security/storage.md) set up, so customer data at rest stays in your cloud
* [ ] [Networking](https://docs.hightouch.com/security/networking) meets your security requirements (if your policy requires changes)
* [ ] If your team uses agents: **Access Agents** and **Configure Agents** granted where needed, and Context Hub owners assigned
* [ ] If you send with Native Delivery: [Prepare for your first send](https://docs.hightouch.com/native-delivery/overview#prepare-for-your-first-send) is complete
* [ ] A marketer's account can sign in and see the right workspace, Spaces, and data
* [ ] Your data team has finished the [Data setup readiness checklist](https://docs.hightouch.com/getting-started/data.md#readiness-checklist)

> [!NOTE]
>
> In smaller teams, one person may own both platform admin and data team responsibilities. The checklist above is organized by responsibility, not job title.

## Next steps

* [Data setup](https://docs.hightouch.com/getting-started/data.md) for your data team to connect sources, configure sync infrastructure, and define the schema.
* [Lifecycle marketing](https://docs.hightouch.com/getting-started/lifecycle.md) for lifecycle marketers to build audiences, run campaigns, and measure results in the workspace you set up.
* [Paid media](https://docs.hightouch.com/getting-started/paid-media.md) for paid media marketers to create, refine, and launch ads with Ad Studio.