Create Workspace

POST/web/v1/workspaces/self JWT

Creates a new workspace owned by the authenticated user. An OWNER role is automatically created and assigned to the creator.

Required Headers

Header	Example Value	Description
Content-Type	application/json	Request content type
Accept	application/json	Expected response type
X-Client-Hash		Client device fingerprint
Accept-Language	en, zh, zh-Hant, ja, vi	Response language (default: en)
Authorization	Bearer	JWT access token
X-Workspace-Id		Target workspace ID

Request Parameters

No query or path parameters required.

Request Body

{
  "workspaceName": "My Payment Workspace",
  "workspaceTimezone": "Asia/Shanghai",
  "extraData": "{\"source\":\"web-portal\"}"
}

Request Example

{
  "workspaceName": "My Workspace",
  "workspaceTimezone": "Asia/Shanghai"
}

Success Response

Status: 201 Created

201 Created 201

{
  "version": "1.3.0",
  "timestamp": 1709337600000,
  "success": true,
  "code": "2001",
  "message": "CREATED",
  "data": {
    "bizId": "ws_abc123def456",
    "institutionBizId": "INST_001",
    "entityBizId": null,
    "workspaceName": "My Payment Workspace",
    "workspaceTimezone": "Asia/Shanghai",
    "workspaceStatus": {
      "value": 10010701,
      "name": "ACTIVE",
      "code": "ACTIVE"
    },
    "workspaceKind": {
      "value": 10010801,
      "name": "LIVE",
      "code": "LIVE"
    },
    "extraData": "{\"source\":\"web-portal\"}",
    "createdAt": "2026-03-22T10:30:00Z",
    "updatedAt": "2026-03-22T10:30:00Z"
  }
}

Response Fields

Field	Type	Description
bizId	String	Unique workspace business ID
institutionBizId	String	Parent institution business ID
entityBizId	String	Associated entity business ID (nullable)
workspaceName	String	Workspace display name
workspaceTimezone	String	IANA timezone identifier
workspaceStatus	Object	Status enum with value, name, code
workspaceKind	Object	Workspace kind (LIVE / SANDBOX)
extraData	String	Free-form JSON string
createdAt	String	ISO 8601 creation timestamp
updatedAt	String	ISO 8601 last update timestamp

Error Responses

Unauthorized 401

{
  "success": false,
  "code": "4010",
  "message": "Invalid or expired token"
}

Conflict 409

{
  "success": false,
  "code": "WORKSPACE.ALREADY_OWNS_WORKSPACE",
  "message": "Tenant account already owns a workspace"
}

Notes

• Returns HTTP 201 with response code "2001" on success.
• workspaceTimezone defaults to "UTC" if omitted or blank.
• TENANT portal accounts are limited to one owned workspace; attempting a second creation returns WORKSPACE.ALREADY_OWNS_WORKSPACE.
• This endpoint operates on the authenticated user's own resources.