Workspaces

Endpoints for listing, creating, and selecting workspaces. A workspace maps to a tenant — an isolated environment for your team.

Overview

A workspace is ZapTicket's unit of multi-tenancy. Each workspace has its own conversations, tickets, agents, settings, and widget configuration. Data never leaks between workspaces.

A user can belong to multiple workspaces (e.g. a freelancer supporting several clients). After authenticating, you list your workspaces and select one to receive a workspace-scoped JWT for subsequent API calls.

Endpoints

List Workspaces

GET/workspaces

List all workspaces the authenticated user belongs to.

Auth: User token

Response 200

{
  "data": [
    {
      "id": "ws_abc123",
      "name": "Acme Inc",
      "slug": "acme-inc",
      "role": "admin",
      "agentCount": 5,
      "createdAt": "2024-01-01T09:00:00Z"
    },
    {
      "id": "ws_xyz789",
      "name": "Side Project",
      "slug": "side-project",
      "role": "agent",
      "agentCount": 2,
      "createdAt": "2024-01-10T14:00:00Z"
    }
  ]
}

Create Workspace

POST/workspaces

Create a new workspace. The creating user becomes the first admin.

Auth: User token

Request Body

{
  "name": "My Startup",
  "slug": "my-startup"
}

The slug must be unique across all workspaces, contain only lowercase letters, numbers, and hyphens, and be between 3-50 characters.

Response 201

{
  "id": "ws_new456",
  "name": "My Startup",
  "slug": "my-startup",
  "role": "admin",
  "siteKey": "zt_pub_abc123def456",
  "createdAt": "2024-01-15T12:00:00Z"
}

💡When a workspace is created, a public site key (zt_pub_...) and HMAC secret (zt_hmac_...) are automatically generated. The site key is returned in the creation response; the HMAC secret is available in Settings.

Select Workspace

POST/workspaces/{id}/select

Get a workspace-scoped JWT for the specified workspace.

Auth: User token

No request body is needed. The workspace ID is in the URL path.

Response 200

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "workspace": {
    "id": "ws_abc123",
    "name": "Acme Inc",
    "slug": "acme-inc",
    "role": "admin"
  },
  "agent": {
    "id": "agt_abc123",
    "fullName": "Jane Smith",
    "role": "admin"
  }
}

The returned token is a workspace-scoped JWT that includes the tenant ID and agent role in its claims. Use this token for all subsequent API calls that access workspace data.

⚠️If the user doesn't belong to the specified workspace, the API returns 403 Forbidden. Workspace tokens expire after 1 hour — use the refresh flow or re-select to get a new token.

Workspace Token Claims

The workspace JWT contains these custom claims:

JWT Payload (decoded)

{
  "sub": "usr_abc123",
  "tenantId": "ws_abc123",
  "agentId": "agt_abc123",
  "role": "admin",
  "iat": 1705312800,
  "exp": 1705316400
}

The backend middleware reads tenantId from the token and applies it as a global query filter — ensuring that every database query is scoped to the correct workspace without any manual filtering in application code.