# Workspace Profile (Coinbax Core API)

> Source: https://developers.coinbax.com/reference/coinbax-core/workspace-profile/
> Staging base URL: https://core-staging.coinbax.com

Reads and self-scoped updates of the caller's own workspace and its
configuration. Destructive or platform-wide workspace administration
(list all, create, delete, avatar) stays private.


## 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/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/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/workspaces/<id> \
  -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

---

## 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/workspaces/<id>/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/workspaces/<id>/platform-mappings \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Retrieved

---

## List sandbox API keys for a workspace

`GET /workspaces/{id}/sandbox-credentials`

- Auth: Bearer token
- Operation ID: `listSandboxCredentials`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |

### Example request

```bash
curl https://core-staging.coinbax.com/workspaces/<id>/sandbox-credentials \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Sandbox credentials returned (never the key material)

**401** Missing or invalid access token

---

## Issue sandbox credentials

`POST /workspaces/{id}/sandbox-credentials`

- Auth: Bearer token
- Operation ID: `createSandboxCredential`

Issues a sandbox credential pair for staging: an OAuth client for the
Payments API **v2**, and an API key that works on **v1** until it
sunsets on 2026-11-01.

Both the key and the OAuth client secret are returned exactly once and
are not retrievable afterwards — store them when issued.

Use `oauthClient` for `/api/v2`: v2 accepts OAuth 2.0 Bearer tokens
only. Exchange the client credentials at
`POST https://api-staging.coinbax.com/api/v2/oauth/token`.

Limits: 2 active credentials per workspace, and issuance is rate
limited to 5 per hour.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/workspaces/<id>/sandbox-credentials \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**201** Credentials issued; returned once and never again

```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": {
    "platformId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "name": "string",
    "apiKey": "string",
    "oauthClient": {
      "clientId": "string",
      "clientSecret": "string",
      "scopes": [
        "string"
      ]
    },
    "scopes": [
      "string"
    ],
    "createdAt": "2026-01-15T12:00:00.000Z",
    "warning": "string"
  }
}
```

**401** Missing or invalid access token

**409** The 2-active credential limit is reached. Revoke one before
issuing another.

**429** Issuance rate limit reached (5 per hour)

---

## Revoke a sandbox API key

`DELETE /workspaces/{id}/sandbox-credentials/{platformId}`

- Auth: Bearer token
- Operation ID: `deleteSandboxCredential`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |
| `platformId` | path | string (uuid) | yes |  |

### Example request

```bash
curl -X DELETE https://core-staging.coinbax.com/workspaces/<id>/sandbox-credentials/<platformId> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**204** Key revoked

**404** No such credential on this workspace

---

## 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/workspaces/<id>/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/workspaces/<id>/wallet-settings \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Updated