# Users (Coinbax Core API)

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

Admin user management

## List all users

`GET /users`

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

Retrieve a paginated list of all users across workspaces.

**Permissions:** ADMIN or SUPER_ADMIN only

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `page` | query | integer | no |  |
| `limit` | query | integer | no |  |
| `workspaceId` | query | string (uuid) | no | Filter by workspace |
| `role` | query | enum ("admin", "client") | no | Filter by role |
| `status` | query | enum ("active", "inactive", "suspended") | no | Filter by status |
| `search` | query | string | no | Search by name or email |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/users \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Users list 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": "550e8400-e29b-41d4-a716-446655440000",
      "email": "admin@coinbax.com",
      "firstName": "Admin",
      "lastName": "User",
      "role": "ADMIN",
      "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
      "emailVerified": true,
      "avatarPath": "/uploads/avatars/user-123.png",
      "createdAt": "2026-01-15T10:00:00.000Z",
      "updatedAt": "2026-02-20T14:30:00.000Z"
    }
  ]
}
```

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**500** Internal server error

---

## Create a new user

`POST /users`

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

Create a new user account.

**Permissions:** ADMIN or SUPER_ADMIN only

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | yes |  |
| `password` | string | yes |  |
| `firstName` | string | no |  |
| `lastName` | string | no |  |
| `role` | enum ("admin", "client") | yes |  |
| `workspaceId` | string (uuid) | no |  |

```json
{
  "email": "newuser@example.com",
  "password": "securePassword123",
  "firstName": "New",
  "lastName": "User",
  "role": "client",
  "workspaceId": "123e4567-e89b-12d3-a456-426614174000"
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/users \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "newuser@example.com",
  "password": "securePassword123",
  "firstName": "New",
  "lastName": "User",
  "role": "client",
  "workspaceId": "123e4567-e89b-12d3-a456-426614174000"
}'
```

### Responses

**201** User created 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": "550e8400-e29b-41d4-a716-446655440000",
    "email": "admin@coinbax.com",
    "firstName": "Admin",
    "lastName": "User",
    "role": "ADMIN",
    "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
    "emailVerified": true,
    "avatarPath": "/uploads/avatars/user-123.png",
    "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

**409** User with this email already exists

**500** Internal server error

---

## Get current user profile

`GET /users/me`

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

Retrieve the authenticated user's full profile information including workspace.

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/users/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** User 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": "550e8400-e29b-41d4-a716-446655440000",
    "email": "admin@coinbax.com",
    "firstName": "Admin",
    "lastName": "User",
    "role": "ADMIN",
    "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
    "emailVerified": true,
    "avatarPath": "/uploads/avatars/user-123.png",
    "createdAt": "2026-01-15T10:00:00.000Z",
    "updatedAt": "2026-02-20T14:30:00.000Z"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**500** Internal server error

---

## Update current user profile

`PUT /users/me`

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

Update the authenticated user's profile information.
Only firstName and lastName can be updated.

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `firstName` | string | no |  |
| `lastName` | string | no |  |

```json
{
  "firstName": "Updated",
  "lastName": "Name"
}
```

### Example request

```bash
curl -X PUT https://core-staging.coinbax.com/api/v1/users/me \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "firstName": "Updated",
  "lastName": "Name"
}'
```

### Responses

**200** Profile 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": "550e8400-e29b-41d4-a716-446655440000",
    "email": "admin@coinbax.com",
    "firstName": "Admin",
    "lastName": "User",
    "role": "ADMIN",
    "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
    "emailVerified": true,
    "avatarPath": "/uploads/avatars/user-123.png",
    "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 user by ID

`GET /users/{id}`

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

Retrieve a user by their unique identifier.

**Permissions:** ADMIN or SUPER_ADMIN only

### Parameters

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

### Example request

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

### Responses

**200** User found

```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": "550e8400-e29b-41d4-a716-446655440000",
    "email": "admin@coinbax.com",
    "firstName": "Admin",
    "lastName": "User",
    "role": "ADMIN",
    "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
    "emailVerified": true,
    "avatarPath": "/uploads/avatars/user-123.png",
    "createdAt": "2026-01-15T10:00:00.000Z",
    "updatedAt": "2026-02-20T14:30:00.000Z"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**404** Resource not found

**500** Internal server error

---

## Update user

`PUT /users/{id}`

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

Update user details.

**Permissions:** ADMIN or SUPER_ADMIN only

### Parameters

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

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | no |  |
| `password` | string | no |  |
| `firstName` | string | no |  |
| `lastName` | string | no |  |
| `role` | enum ("admin", "client") | no |  |
| `status` | enum ("active", "inactive", "suspended") | no |  |
| `workspaceId` | string (uuid) | no |  |

```json
{
  "email": "developer@example.com",
  "password": "string",
  "firstName": "string",
  "lastName": "string",
  "role": "admin",
  "status": "active",
  "workspaceId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d"
}
```

### Example request

```bash
curl -X PUT https://core-staging.coinbax.com/api/v1/users/<id> \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "developer@example.com",
  "password": "string",
  "firstName": "string",
  "lastName": "string",
  "role": "admin",
  "status": "active",
  "workspaceId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d"
}'
```

### Responses

**200** User 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": "550e8400-e29b-41d4-a716-446655440000",
    "email": "admin@coinbax.com",
    "firstName": "Admin",
    "lastName": "User",
    "role": "ADMIN",
    "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
    "emailVerified": true,
    "avatarPath": "/uploads/avatars/user-123.png",
    "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 user

`DELETE /users/{id}`

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

Permanently delete a user.

**Permissions:** ADMIN or SUPER_ADMIN only

### Parameters

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

### Example request

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

### Responses

**200** User deleted 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": {
    "message": "User deleted successfully"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**404** Resource not found

**500** Internal server error

---

## Upload user avatar

`POST /users/me/avatar`

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

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/users/me/avatar \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Uploaded

---

## Delete user avatar

`DELETE /users/me/avatar`

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

### Example request

```bash
curl -X DELETE https://core-staging.coinbax.com/api/v1/users/me/avatar \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**204** Deleted

---

## Update password

`PATCH /users/me/password`

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

### Example request

```bash
curl -X PATCH https://core-staging.coinbax.com/api/v1/users/me/password \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Updated

---

## Get user audit logs

`GET /users/{id}/audit-logs`

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

### Parameters

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

### Example request

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

### Responses

**200** Retrieved