# Workspaces

Source: https://developer.nylas.com/docs/reference/api/workspaces/

Workspaces group and organize grants in a Nylas application by a common attribute, such as the email address domain (for example, `nylas.com`).

## Assign grants to workspaces

Nylas offers two endpoints to manage workspaces and the grants they contain:

- [**Automatically Group Grants into Workspaces**](/docs/reference/api/workspaces/autogroup-workspace/): Starts a background job that, based on your filters, processes existing grants in your Nylas application and automatically sorts them to existing workspaces. If necessary, Nylas automatically creates new workspaces.
- [**Update Workspace Assignments**](/docs/reference/api/workspaces/manually-assign-workspace/): Manually specify a workspace ID and up to 500 grants to add or remove from that workspace.

## Default workspace

A Nylas application can have a _default workspace_, which Nylas creates automatically when the application is created and manages on your behalf. Applications created before default workspaces were introduced might not have one. When you retrieve workspaces, Nylas identifies the default workspace with `"default": true`, and the application object exposes its ID as `default_workspace_id`.

When a new grant is created without an explicit `workspace_id`, Nylas first tries to auto-group it into a workspace that has `auto_group` enabled and a `domain` that matches the grant's email address domain. If no domain workspace matches, Nylas assigns the grant to the application's default workspace, if one exists.

The default workspace is protected: you can update only its `policy_id` and `rule_ids` values (changes to `name` or `auto_group` return an error), and you can't delete it. A workspace's `domain` can't be changed after creation, on any workspace.

## Policies and rules

Workspaces can carry a [policy](/docs/v3/agent-accounts/policies-rules-lists/) (`policy_id`) and [rules](/docs/v3/agent-accounts/policies-rules-lists/#rules) (`rule_ids`). Agent Accounts in a workspace use the policy attached to the workspace for limits and spam settings, and the rules attached to the workspace for mail filtering.

## Workspace limitations

- Workspaces are designed to group grants by the top-level domain (TLD) of users' email addresses. Nylas allows you to manually assign grants to any workspace, but that workspace must have `auto_group` set to `false`.
- When `auto_group` is set to `false`, Nylas doesn't automatically assign grants to that workspace. You'll need to manually assign grants to the workspace using the [Update Workspace Assignments endpoint](/docs/reference/api/workspaces/manually-assign-workspace/).
- When `auto_group` is `true`, Nylas automatically assigns new grants to the workspace. You can move grants to a different workspace by making an [Update Workspace Assignments request](/docs/reference/api/workspaces/manually-assign-workspace/).


## Endpoints

- **GET** `/v3/workspaces` - [Return all workspaces](https://developer.nylas.com/docs/reference/api/workspaces/get-all-workspaces/)
- **POST** `/v3/workspaces` - [Create a workspace](https://developer.nylas.com/docs/reference/api/workspaces/create-workspace/)
- **GET** `/v3/workspaces/{workspace_id}` - [Return a workspace](https://developer.nylas.com/docs/reference/api/workspaces/get-workspace/)
- **PATCH** `/v3/workspaces/{workspace_id}` - [Update a workspace](https://developer.nylas.com/docs/reference/api/workspaces/update-workspace/)
- **DELETE** `/v3/workspaces/{workspace_id}` - [Delete a workspace](https://developer.nylas.com/docs/reference/api/workspaces/delete-workspace/)
- **POST** `/v3/workspaces/auto-group` - [Automatically group grants into workspace](https://developer.nylas.com/docs/reference/api/workspaces/autogroup-workspace/)
- **POST** `/v3/workspaces/{workspace_id}/manual-assign` - [Update workspace assignments](https://developer.nylas.com/docs/reference/api/workspaces/manually-assign-workspace/)