Create Your First Workspace

In this tutorial you will create a workspace, set it as your default, invite a team member, and update a member's role — the full lifecycle for setting up collaborative access in Chainabit.

Prerequisites

• A Chainabit account with a valid access token
• curl available in your terminal

Set your environment variables:

export BASE_URL="https://api.chainabit.com/api/v1"
export TOKEN="your-access-token"

Get your access token by calling POST /auth/login.

---

Step 1: List Your Existing Workspaces

Before creating a new workspace, check what you already have:

curl -s "$BASE_URL/workspaces" \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "data": [],
  "meta": { "total": 0 },
  "error": null
}

New accounts start with an empty workspace list.

---

Step 2: Create a Workspace

Create a workspace by posting a name and an optional description:

curl -s -X POST "$BASE_URL/workspaces" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Team",
    "description": "Workspace for the product and design team"
  }'

Response:

{
  "data": {
    "id": "ws_01HQS...",
    "name": "Product Team",
    "description": "Workspace for the product and design team",
    "isDefault": false,
    "isActive": true,
    "createdAt": "2026-05-26T10:00:00.000Z"
  },
  "meta": null,
  "error": null
}

Save the workspace ID:

export WORKSPACE_ID="ws_01HQS..."

---

Step 3: Set the Workspace as Default

The default workspace is used as the implicit context when no workspace is specified in API calls. Set yours:

curl -s -X PUT "$BASE_URL/workspaces/$WORKSPACE_ID/default" \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "data": {
    "id": "ws_01HQS...",
    "name": "Product Team",
    "isDefault": true
  },
  "meta": null,
  "error": null
}

---

Step 4: Invite a Team Member

Add a team member to the workspace by their Chainer ID. You can find a user's Chainer ID from the Identity API.

Roles: owner, admin, member, viewer. Owners can manage all workspace settings. Members can use the workspace. Viewers have read-only access.

curl -s -X POST "$BASE_URL/workspaces/$WORKSPACE_ID/members" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chainerId": "chainer_01HQT...",
    "role": "member"
  }'

Response:

{
  "data": {
    "chainerId": "chainer_01HQT...",
    "role": "member",
    "joinedAt": "2026-05-26T10:05:00.000Z"
  },
  "meta": null,
  "error": null
}

---

Step 5: List Workspace Members

Confirm the invitation succeeded:

curl -s "$BASE_URL/workspaces/$WORKSPACE_ID/members" \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "data": [
    {
      "chainerId": "chainer_01HQR...",
      "role": "owner",
      "joinedAt": "2026-05-26T10:00:00.000Z"
    },
    {
      "chainerId": "chainer_01HQT...",
      "role": "member",
      "joinedAt": "2026-05-26T10:05:00.000Z"
    }
  ],
  "meta": { "total": 2 },
  "error": null
}

---

Step 6: Update a Member's Role

Promote the member to admin so they can manage workspace settings:

curl -s -X PATCH "$BASE_URL/workspaces/$WORKSPACE_ID/members/chainer_01HQT..." \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "role": "admin" }'

Response:

{
  "data": {
    "chainerId": "chainer_01HQT...",
    "role": "admin"
  },
  "meta": null,
  "error": null
}

---

Summary

In this tutorial you:

1. Listed existing workspaces
2. Created a new workspace
3. Set it as default for implicit API context
4. Invited a team member with a role
5. Listed members to confirm the invitation
6. Updated a member's role to grant admin access

Next Steps

• Accounts & Workspaces API Reference for the full endpoint contract
• API Keys to create workspace-scoped API keys
• Tool Policies to configure which AI tools your workspace can access
• Chain Triggers to run chains (workflows) on cron/event triggers in your new workspace