# How Agent Account workspaces work

Source: https://developer.nylas.com/docs/v3/agent-accounts/workspaces/

A workspace groups the Agent Accounts in your application by a shared attribute, usually their email domain, and carries the policy and rules that govern every account inside it. Instead of setting limits and mail filtering on each grant one at a time, you configure them once on the workspace and every member inherits them. This page covers how workspaces work, how to create one, and how accounts get assigned.

> **Info:** 
> **New to Agent Accounts?** Start with the [Agent Accounts quickstart](/docs/v3/getting-started/agent-accounts/) to provision your first account, then come back to organize accounts into workspaces.

## What is a workspace?

A workspace is a container that groups Agent Accounts and holds one `policy_id` plus an array of `rule_ids`. Every account in the workspace inherits that policy's limits and spam settings, and runs the workspace's rules on its mail. The policy sets send caps (for example, 200 messages per account per day on the free plan), storage, and retention.

The pieces form a chain. A [policy](/docs/v3/agent-accounts/policies-rules-lists/) bundles limits and spam detection, [rules](/docs/v3/agent-accounts/policies-rules-lists/#rules) describe match conditions and actions, and a workspace references one policy and a list of rules. A grant carries a `workspace_id` that points at its workspace, so changing the workspace's policy reconfigures every account in it at once.

## Create a workspace

Create a workspace with a `POST /v3/workspaces` request. You can set 5 fields: `name`, `domain`, `auto_group`, `policy_id`, and `rule_ids`. The `domain` ties the workspace to one email domain, and `auto_group` controls whether matching accounts join it automatically. The response returns the `workspace_id` you store on grants.

```bash
curl --request POST \
  --url "https://api.us.nylas.com/v3/workspaces" \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "The Nylas Workspace",
    "domain": "nylas.com",
    "auto_group": true,
    "policy_id": "<POLICY_ID>",
    "rule_ids": ["<RULE_ID>"]
  }'


```

A workspace with no `policy_id` runs its accounts at your billing plan's maximum limits, so you can create the grouping first and attach a policy later. To attach or change the policy, see [Attach a policy to a workspace](/docs/v3/agent-accounts/policies-rules-lists/#attach-a-policy-to-a-workspace).

## Assign Agent Accounts to a workspace

An Agent Account joins a workspace one of three ways: you pass a `workspace_id` when you create the grant, the account is auto-grouped by domain when `auto_group` is `true`, or you assign it manually after the fact. Manual assignment moves up to 500 grants per request across 2 fields, `assign_grants` and `remove_grants`.

The Update Workspace Assignments endpoint, `POST /v3/workspaces/{workspace_id}/manual-assign`, adds or removes specific grants from a workspace whose `auto_group` is `false`. Send grant IDs in `assign_grants`, `remove_grants`, or both, with up to 500 IDs per list.

```bash
curl --request POST \
  --url "https://api.us.nylas.com/v3/workspaces/<WORKSPACE_ID>/manual-assign" \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "assign_grants": [
      "10726e7c-89c3-4a1d-9f4a-5f3f37f6f2d9",
      "3b9f5c1a-21d4-46c1-b84f-0e8d1f9eaa42"
    ],
    "remove_grants": [
      "5f1a2c9e-739b-4c66-9a3d-2c88a0c6d123",
      "9c6e4b7d-2e4a-4ef0-a1b8-badf5a76a555"
    ]
  }'

```

To set a workspace at creation time, pass `workspace_id` on [`POST /v3/connect/custom`](/docs/v3/agent-accounts/provisioning/#create-an-agent-account). To sort existing grants in bulk by domain, use the [Automatically Group Grants endpoint](/docs/reference/api/workspaces/autogroup-workspace/), which runs a background job and creates new domain workspaces when needed.

## The default workspace

Every application has exactly 1 default workspace that Nylas creates and manages automatically. Any Agent Account created without a `workspace_id`, and not auto-grouped by domain, lands here. The application object exposes its ID as `default_workspace_id`. You can update only 2 fields on it, `policy_id` and `rule_ids`, and you can't delete it.

Attach your policy and rules to the default workspace to cover every unassigned account in one place. Applications created before default workspaces existed might not have one, so check for `default_workspace_id` on the application before you rely on it.

## Things to know about workspaces

A few constraints shape how you design your grouping. A workspace's `domain` is fixed at creation and can't change afterward, on any workspace. The default workspace is protected: renaming it, toggling its `auto_group`, or deleting it returns an error, and you can update just 2 fields on it. Manual assignment works only when a workspace's `auto_group` is `false`.

These constraints favor a clear plan up front. Use one workspace per agent archetype (a sales-outreach group and a support-triage group have different send limits and spam tolerances), set each workspace's `domain` when you create it, and decide early whether accounts join by domain matching or by explicit assignment.

## What's next

- [Policies, Rules, and Lists](/docs/v3/agent-accounts/policies-rules-lists/) to configure the limits and rules a workspace carries
- [Provisioning Agent Accounts](/docs/v3/agent-accounts/provisioning/) to create accounts and set their `workspace_id`
- [Workspaces API reference](/docs/reference/api/workspaces/) for the full endpoint set, including auto-group and manual-assign