# Workspace Customers (Coinbax Core API)

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

Customer management within workspaces

## List workspace customers

`GET /workspaces/{id}/customers`

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

Retrieve a paginated list of customers belonging to a specific workspace.

**Permissions:** ADMIN or SUPER_ADMIN only

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace UUID |
| `page` | query | integer | no | Page number (1-indexed) |
| `limit` | query | integer | no | Items per page |
| `status` | query | enum ("active", "inactive", "suspended", "pending") | no | Filter by customer status |
| `search` | query | string | no | Search by name or email |

### Example request

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

### Responses

**200** Customers list retrieved successfully

```json
{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
      "email": "john.doe@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "status": "active",
      "createdAt": "2026-01-20T08:30:00.000Z",
      "updatedAt": "2026-02-15T16:45:00.000Z"
    }
  ],
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 100,
      "totalPages": 5
    }
  }
}
```

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**404** Resource not found

**500** Internal server error

---

## Create customer in workspace

`POST /workspaces/{id}/customers`

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

Create a new customer within a specific workspace.

**Permissions:** ADMIN or SUPER_ADMIN only

### Parameters

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

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | yes |  |
| `firstName` | string | yes |  |
| `lastName` | string | yes |  |
| `phoneNumber` | string | no |  |
| `address` | string | no |  |
| `city` | string | no |  |
| `state` | string | no |  |
| `postalCode` | string | no |  |
| `country` | string | no |  |
| `metadata` | object | no |  |

```json
{
  "email": "john.doe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "phoneNumber": "+1-555-123-4567",
  "address": "123 Main St",
  "city": "San Francisco",
  "state": "CA",
  "postalCode": "94102",
  "country": "USA",
  "metadata": {}
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/<id>/customers \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "john.doe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "phoneNumber": "+1-555-123-4567",
  "address": "123 Main St",
  "city": "San Francisco",
  "state": "CA",
  "postalCode": "94102",
  "country": "USA",
  "metadata": {}
}'
```

### Responses

**201** Customer created successfully

```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "status": "active",
    "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

**404** Resource not found

**500** Internal server error

---

## Register customer

`POST /workspaces/{id}/customers/auth/register`

- Auth: Public (no authentication)
- Operation ID: `registerWorkspaceCustomer`

Register a new customer for a workspace.

**Authentication:** Public endpoint (no auth required)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Workspace ID or slug |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | yes |  |
| `password` | string | yes |  |
| `firstName` | string | no |  |
| `lastName` | string | no |  |

```json
{
  "email": "customer@example.com",
  "password": "securePassword123",
  "firstName": "John",
  "lastName": "Doe"
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/<id>/customers/auth/register \
  -H "Content-Type: application/json" \
  -d '{
  "email": "customer@example.com",
  "password": "securePassword123",
  "firstName": "John",
  "lastName": "Doe"
}'
```

### Responses

**201** Customer registered 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": {
    "customer": {
      "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "email": "developer@example.com",
      "firstName": "string",
      "lastName": "string",
      "walletAddress": "string",
      "status": "pending"
    },
    "accessToken": "string",
    "refreshToken": "string",
    "expiresIn": 100
  }
}
```

**400** Bad request - validation error

**409** Conflict - resource already exists or state conflict

**500** Internal server error

---

## Login customer

`POST /workspaces/{id}/customers/auth/login`

- Auth: Public (no authentication)
- Operation ID: `loginWorkspaceCustomer`

Authenticate a customer and receive access tokens.

**Authentication:** Public endpoint (no auth required)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Workspace ID or slug |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | yes |  |
| `password` | string | yes |  |

```json
{
  "email": "customer@example.com",
  "password": "securePassword123"
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/<id>/customers/auth/login \
  -H "Content-Type: application/json" \
  -d '{
  "email": "customer@example.com",
  "password": "securePassword123"
}'
```

### Responses

**200** Customer logged in 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": {
    "customer": {
      "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "email": "developer@example.com",
      "firstName": "string",
      "lastName": "string",
      "walletAddress": "string",
      "status": "pending"
    },
    "accessToken": "string",
    "refreshToken": "string",
    "expiresIn": 100
  }
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**500** Internal server error

---

## Get current customer

`GET /workspaces/{id}/customers/auth/me`

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

Get the current authenticated customer's profile.

**Requires:** Customer authentication (workspace-specific JWT)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Workspace ID or slug |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/<id>/customers/auth/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Customer profile retrieved 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": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "email": "developer@example.com",
    "firstName": "string",
    "lastName": "string",
    "walletAddress": "string",
    "walletLinkedAt": "2026-01-15T12:00:00.000Z",
    "emailVerified": true,
    "status": "pending"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**500** Internal server error

---

## Refresh customer token

`POST /workspaces/{id}/customers/auth/refresh`

- Auth: Public (no authentication)
- Operation ID: `refreshWorkspaceCustomerToken`

Refresh an expired access token using a refresh token.

**Authentication:** Public endpoint (no auth required)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Workspace ID or slug |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `refreshToken` | string | yes |  |

```json
{
  "refreshToken": "string"
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/<id>/customers/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
  "refreshToken": "string"
}'
```

### Responses

**200** Token refreshed 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": {
    "customer": {
      "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "email": "developer@example.com",
      "firstName": "string",
      "lastName": "string",
      "walletAddress": "string",
      "status": "pending"
    },
    "accessToken": "string",
    "refreshToken": "string",
    "expiresIn": 100
  }
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**500** Internal server error

---

## Link wallet to customer

`POST /workspaces/{id}/customers/auth/link-wallet`

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

Link an external wallet address to the customer account.
Requires signature verification to prove wallet ownership.

**Requires:** Customer authentication (workspace-specific JWT)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Workspace ID or slug |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `walletAddress` | string | yes | Ethereum wallet address |
| `signature` | string | yes | Signed message proving wallet ownership |
| `message` | string | yes | Original message that was signed |

```json
{
  "walletAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "signature": "0x...",
  "message": "Link wallet to Coinbax: 1234567890"
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/<id>/customers/auth/link-wallet \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "walletAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "signature": "0x...",
  "message": "Link wallet to Coinbax: 1234567890"
}'
```

### Responses

**200** Wallet linked 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": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "email": "developer@example.com",
    "firstName": "string",
    "lastName": "string",
    "walletAddress": "string",
    "walletLinkedAt": "2026-01-15T12:00:00.000Z",
    "emailVerified": true,
    "status": "pending"
  }
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**500** Internal server error

---

## Get customer wallet

`GET /workspaces/{id}/customers/auth/wallet`

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

Get the linked wallet address for the current customer.

**Requires:** Customer authentication (workspace-specific JWT)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Workspace ID or slug |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/<id>/customers/auth/wallet \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Wallet information retrieved 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": {
    "walletAddress": "string",
    "walletLinkedAt": "2026-01-15T12:00:00.000Z"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**500** Internal server error