---
question: Which organization roles can create a workspace?
kind: task
via_web: available
via_cli: available
via_python: na
via_api: available
via_config: available
ref_web: Organization Settings › Workspaces
ref_cli: abi workspace create
ref_api: POST /api/workspaces
ref_config: organizations[].workspaces
prereq: You are an owner or admin of the organization the workspace goes in.
next:
  - /capabilities/platform/invite-a-workspace-member
  - /capabilities/platform/workspace-settings
---

# Create a workspace

A [business workspace](/user-guide/platform/business-workspaces) belongs to an organization. Whoever creates it becomes its owner, and the organization's owners and admins reach it too. The slug is set at creation and cannot change later: lowercase letters, digits and dashes, at least two characters, no dash at either end.

## Web UI

### Open the organization's workspaces

Open the account menu, then **Organization Settings**. With one organization you land on its settings; otherwise pick it in the Organizations list. Select **Workspaces** in the nav.

### Fill in the form

Choose **Create workspace**. Enter the **Workspace name**. The **Slug** fills from the name; change it now if you need to. **Group**, **Description**, the logo, **Primary Color** and **Accent Color** are optional.

![Organization Settings on Workspaces: the Create workspace form](/abi/Screenshot_Create_Workspace.png)

*Organization Settings › Workspaces › Create workspace. The slug fills from the name; group, description, logo and colors are optional.*

### Create it

Choose **Create workspace**. The button is disabled for members of the organization: "Only organization owners and admins can create workspaces".

## CLI

### Find the organization id

```bash
abi org list
```

### Create the workspace

```bash
abi workspace create --name "Research" --slug research --org <org-id>
```

All three options are required. The command calls `POST /api/workspaces` as you and prints the new workspace. It signs in with `--token` (`NEXUS_ACCESS_TOKEN`), or with `--auth-email` and `--auth-password` (`NEXUS_EMAIL`, `NEXUS_PASSWORD`), against `--api-url` (`NEXUS_API_URL`, default `http://localhost:9879`). `--dry-run` prints the request without sending it. See [`abi workspace create`](/user-guide/reference/cli#abi-workspace-create).

## Python

Not applicable. ABI has no Python API for Nexus workspaces. From Python, call the REST API.

## REST API

### Sign in

`POST /api/auth/login` returns an access token. Send it as `Authorization: Bearer <token>`.

### Create the workspace

```bash
curl -X POST http://localhost:9879/api/workspaces \
  -H "Authorization: Bearer $NEXUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Research", "slug": "research", "organization_id": "<org-id>"}'
```

`name` and `slug` are required. Optional fields include `description` (200 characters), `workspace_group`, `logo_url`, `primary_color` and `accent_color`. The response is the workspace, with an id that starts with `ws-` and `current_user_role: "owner"`. A slug in use answers 400 "Slug already exists". With `organization_id`, a caller who is not an owner or admin of that organization gets 403.

## Config

### Add the workspace under its organization

Workspaces are listed under an organization in `nexus_config`, in the `naas_abi` module's config. There is no top-level `workspaces:` key.

```yaml title="config.yaml"
nexus_config:
  organizations:
    - name: "Dev"
      slug: "dev"
      owner_email: "admin@example.com"
      workspaces:
        - name: "Default"
          slug: "default"
          owner_email: "admin@example.com"
        - name: "Research"
          slug: "research"
```

`slug` is required. `owner_email` defaults to the organization's owner, which is also used when the named user does not exist. The workspace is skipped only when neither can be found. `members:` is deprecated and ignored: add people with [Invite a workspace member](/user-guide/platform/invite-a-workspace-member).

### Restart the API

The list is applied when the API starts, by slug. A new slug creates the workspace. On an existing one, the name and branding only fill empty fields, so a change made in Nexus is kept, and the owner's role is set back to owner.