# Workspaces (Coinbax Core API) > Source: https://developers.coinbax.com/reference/coinbax-core/workspaces/ > Staging base URL: https://core-staging.coinbax.com/api/v1 Workspace (tenant) management ## List all workspaces `GET /workspaces` - Auth: Bearer token - Operation ID: `listWorkspaces` Retrieve a paginated list of all workspaces. **Permissions:** ADMIN or SUPER_ADMIN only ### Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `page` | query | integer | no | Page number (1-indexed) | | `limit` | query | integer | no | Items per page | ### Example request ```bash curl https://core-staging.coinbax.com/api/v1/workspaces \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ### Responses **200** Workspaces list retrieved successfully ```json { "success": true, "data": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "Acme Corp", "slug": "acme-corp", "email": "contact@acme.com", "status": "active", "walletProvider": "TURNKEY", "createdAt": "2026-01-15T10:00:00.000Z", "updatedAt": "2026-02-20T14:30:00.000Z" } ], "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000", "pagination": { "page": 1, "limit": 20, "total": 50, "totalPages": 3 } } } ``` **401** Unauthorized - missing or invalid authentication **403** Forbidden - insufficient permissions **500** Internal server error --- ## Create a new workspace `POST /workspaces` - Auth: Bearer token - Operation ID: `createWorkspace` Create a new workspace (tenant) in the system. **Permissions:** ADMIN or SUPER_ADMIN only ### Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | yes | Workspace display name | | `slug` | string | no | URL-friendly identifier (auto-generated if not provided) | | `email` | string (email) | yes | Workspace contact email | | `status` | enum ("active", "inactive", "suspended", "pending") | no | Initial workspace status | | `webhookUrl` | string (uri) | no | Webhook URL for transaction events | | `walletProvider` | enum ("COINBAX", "CIRCLE", "FIREBLOCKS", "TURNKEY", "UTILA") | no | Wallet provider to use | | `metadata` | object | no | Custom metadata | ```json { "name": "Acme Corp", "email": "contact@acme.com", "walletProvider": "TURNKEY", "metadata": { "industry": "fintech" } } ``` ### Example request ```bash curl -X POST https://core-staging.coinbax.com/api/v1/workspaces \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Acme Corp", "email": "contact@acme.com", "walletProvider": "TURNKEY", "metadata": { "industry": "fintech" } }' ``` ### Responses **201** Workspace created successfully ```json { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "Acme Corp", "slug": "acme-corp", "email": "contact@acme.com", "status": "pending", "walletProvider": "TURNKEY", "metadata": { "industry": "fintech" }, "createdAt": "2026-02-24T12:00:00.000Z", "updatedAt": "2026-02-24T12:00:00.000Z" }, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000" } } ``` **400** Bad request - validation error **401** Unauthorized - missing or invalid authentication **403** Forbidden - insufficient permissions **409** Workspace with this slug already exists **500** Internal server error --- ## Get current user's workspace `GET /workspaces/me` - Auth: Bearer token - Operation ID: `getMyWorkspace` Retrieve the workspace associated with the currently authenticated user. ### Example request ```bash curl https://core-staging.coinbax.com/api/v1/workspaces/me \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ### Responses **200** Workspace retrieved successfully ```json { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "Acme Corp", "slug": "acme-corp", "email": "contact@acme.com", "status": "active", "walletProvider": "TURNKEY", "createdAt": "2026-01-15T10:00:00.000Z", "updatedAt": "2026-02-20T14:30:00.000Z" }, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000" } } ``` **400** User has no associated workspace **401** Unauthorized - missing or invalid authentication **500** Internal server error --- ## Update current user's workspace `PUT /workspaces/me` - Auth: Bearer token - Operation ID: `updateMyWorkspace` Update the workspace associated with the currently authenticated user. Allows workspace members to update their own organization details. ### Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | no | Workspace display name | | `email` | string (email) | no | Workspace contact email | | `status` | enum ("active", "inactive", "suspended", "pending") | no | Workspace status | | `avatarPath` | string | no | Path to workspace avatar image | | `webhookUrl` | string (uri) | no | Webhook URL for transaction events | | `walletProvider` | enum ("COINBAX", "CIRCLE", "FIREBLOCKS", "TURNKEY", "UTILA") | no | Wallet provider to use | | `metadata` | object | no | Custom metadata | ```json { "name": "Acme Corporation", "email": "admin@acme.com", "webhookUrl": "https://acme.com/webhooks/coinbax-v2" } ``` ### Example request ```bash curl -X PUT https://core-staging.coinbax.com/api/v1/workspaces/me \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Acme Corporation", "email": "admin@acme.com", "webhookUrl": "https://acme.com/webhooks/coinbax-v2" }' ``` ### Responses **200** Workspace updated successfully ```json { "success": true, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000", "pagination": { "page": 1, "limit": 20, "total": 150, "totalPages": 8 } }, "data": { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "Acme Corp", "slug": "acme-corp", "email": "contact@acme.com", "status": "active", "avatarPath": "/uploads/avatars/workspace-123.png", "webhookUrl": "https://acme.com/webhooks/coinbax", "walletProvider": "TURNKEY", "walletId": "wallet_abc123", "turnkeyOrganizationId": "org_turnkey_xyz", "metadata": { "industry": "fintech", "tier": "enterprise" }, "billingEnabled": false, "createdAt": "2026-01-15T10:00:00.000Z", "updatedAt": "2026-02-20T14:30:00.000Z" } } ``` **400** Bad request - validation error **401** Unauthorized - missing or invalid authentication **500** Internal server error --- ## Get workspace by ID `GET /workspaces/{id}` - Auth: Bearer token - Operation ID: `getWorkspace` Retrieve a workspace by its unique identifier. **Permissions:** - User must be a member of the workspace OR - User must be ADMIN or SUPER_ADMIN ### Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string (uuid) | yes | Workspace UUID | ### Example request ```bash curl https://core-staging.coinbax.com/api/v1/workspaces/ \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ### Responses **200** Workspace found ```json { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "Acme Corp", "slug": "acme-corp", "email": "contact@acme.com", "status": "active", "walletProvider": "TURNKEY", "webhookUrl": "https://acme.com/webhooks/coinbax", "createdAt": "2026-01-15T10:00:00.000Z", "updatedAt": "2026-02-20T14:30:00.000Z" }, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000" } } ``` **401** Unauthorized - missing or invalid authentication **403** Access denied - not a member of this workspace **404** Resource not found **500** Internal server error --- ## Update workspace `PUT /workspaces/{id}` - Auth: Bearer token - Operation ID: `updateWorkspace` Update workspace details. **Permissions:** ADMIN or SUPER_ADMIN only ### Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string (uuid) | yes | | ### Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | no | Workspace display name | | `email` | string (email) | no | Workspace contact email | | `status` | enum ("active", "inactive", "suspended", "pending") | no | Workspace status | | `avatarPath` | string | no | Path to workspace avatar image | | `webhookUrl` | string (uri) | no | Webhook URL for transaction events | | `walletProvider` | enum ("COINBAX", "CIRCLE", "FIREBLOCKS", "TURNKEY", "UTILA") | no | Wallet provider to use | | `metadata` | object | no | Custom metadata | ```json { "name": "Acme Corporation", "email": "admin@acme.com", "webhookUrl": "https://acme.com/webhooks/coinbax-v2" } ``` ### Example request ```bash curl -X PUT https://core-staging.coinbax.com/api/v1/workspaces/ \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Acme Corporation", "email": "admin@acme.com", "webhookUrl": "https://acme.com/webhooks/coinbax-v2" }' ``` ### Responses **200** Workspace updated successfully ```json { "success": true, "meta": { "timestamp": "2026-02-24T12:00:00.000Z", "requestId": "550e8400-e29b-41d4-a716-446655440000", "pagination": { "page": 1, "limit": 20, "total": 150, "totalPages": 8 } }, "data": { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "Acme Corp", "slug": "acme-corp", "email": "contact@acme.com", "status": "active", "avatarPath": "/uploads/avatars/workspace-123.png", "webhookUrl": "https://acme.com/webhooks/coinbax", "walletProvider": "TURNKEY", "walletId": "wallet_abc123", "turnkeyOrganizationId": "org_turnkey_xyz", "metadata": { "industry": "fintech", "tier": "enterprise" }, "billingEnabled": false, "createdAt": "2026-01-15T10:00:00.000Z", "updatedAt": "2026-02-20T14:30:00.000Z" } } ``` **400** Bad request - validation error **401** Unauthorized - missing or invalid authentication **403** Forbidden - insufficient permissions **404** Resource not found **500** Internal server error --- ## Delete workspace `DELETE /workspaces/{id}` - Auth: Bearer token - Operation ID: `deleteWorkspace` Permanently delete a workspace. **Permissions:** ADMIN or SUPER_ADMIN only **Warning:** This action is irreversible and will delete all associated data. ### Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string (uuid) | yes | | ### Example request ```bash curl -X DELETE https://core-staging.coinbax.com/api/v1/workspaces/ \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ### Responses **204** Workspace deleted successfully (no content) **401** Unauthorized - missing or invalid authentication **403** Forbidden - insufficient permissions **404** Resource not found **500** Internal server error --- ## Upload workspace avatar `POST /workspaces/{id}/avatar` - Auth: Bearer token - Operation ID: `uploadWorkspaceAvatar` ### Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string (uuid) | yes | | ### Example request ```bash curl -X POST https://core-staging.coinbax.com/api/v1/workspaces//avatar \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ### Responses **200** Uploaded --- ## Delete workspace avatar `DELETE /workspaces/{id}/avatar` - Auth: Bearer token - Operation ID: `deleteWorkspaceAvatar` ### Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string (uuid) | yes | | ### Example request ```bash curl -X DELETE https://core-staging.coinbax.com/api/v1/workspaces//avatar \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ### Responses **204** Deleted --- ## Get workspace billing `GET /workspaces/{id}/billing` - Auth: Bearer token - Operation ID: `getWorkspaceBilling` ### Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string (uuid) | yes | | ### Example request ```bash curl https://core-staging.coinbax.com/api/v1/workspaces//billing \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ### Responses **200** Retrieved --- ## List platform mappings `GET /workspaces/{id}/platform-mappings` - Auth: Bearer token - Operation ID: `listWorkspacePlatformMappings` ### Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string (uuid) | yes | | ### Example request ```bash curl https://core-staging.coinbax.com/api/v1/workspaces//platform-mappings \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ### Responses **200** Retrieved --- ## Create platform mapping `POST /workspaces/{id}/platform-mappings` - Auth: Bearer token - Operation ID: `createWorkspacePlatformMapping` ### Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string (uuid) | yes | | ### Example request ```bash curl -X POST https://core-staging.coinbax.com/api/v1/workspaces//platform-mappings \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ### Responses **201** Created --- ## Delete platform mapping `DELETE /workspaces/{id}/platform-mappings/{mappingId}` - Auth: Bearer token - Operation ID: `deleteWorkspacePlatformMapping` ### Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string (uuid) | yes | | | `mappingId` | path | string (uuid) | yes | | ### Example request ```bash curl -X DELETE https://core-staging.coinbax.com/api/v1/workspaces//platform-mappings/ \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ### Responses **204** Deleted --- ## Get wallet settings `GET /workspaces/{id}/wallet-settings` - Auth: Bearer token - Operation ID: `getWorkspaceWalletSettings` ### Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string (uuid) | yes | | ### Example request ```bash curl https://core-staging.coinbax.com/api/v1/workspaces//wallet-settings \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ### Responses **200** Retrieved --- ## Update wallet settings `PATCH /workspaces/{id}/wallet-settings` - Auth: Bearer token - Operation ID: `updateWorkspaceWalletSettings` ### Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string (uuid) | yes | | ### Example request ```bash curl -X PATCH https://core-staging.coinbax.com/api/v1/workspaces//wallet-settings \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ### Responses **200** Updated --- ## Search workspaces `GET /workspaces/search` - Auth: Bearer token - Operation ID: `searchWorkspaces` ### Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `q` | query | string | yes | | ### Example request ```bash curl https://core-staging.coinbax.com/api/v1/workspaces/search?q= \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ### Responses **200** Results