# Bind client

**Endpoint**

`PUT/v2/user/{uuid}/relate-client`

**Link**

{% embed url="<https://stagep.tst-apidmndelss.com/openapi/v2.html#/operations/Users_AddRelationClient>" %}

### **Request**

#### **Authentication**

An API key is required for authentication. Include it in the `Authorization` header.

* **Header:** `Authorization`
* **Value:** Your API key token

#### **HTTP Method & URL**

* **Method:** `PUT`
* **URL:** `https://stagep.tst-apidmndelss.com/v2/user/{uuid}/relate-client`

#### **Path Parameters**

| Parameter  | Type     | Description                        | Required | Example          |
| ---------- | -------- | ---------------------------------- | -------- | ---------------- |
| **`uuid`** | `string` | **Unique identifier of the user**. | Yes      | `user_abc123def` |

#### **Headers**

| Key             | Value              | Required |
| --------------- | ------------------ | -------- |
| `Authorization` | `Bearer <JWT>`     | Yes      |
| `Accept`        | `application/json` | Yes      |
| `Content-Type`  | `application/json` | Yes      |

#### **Request Body (JSON)**

| Field           | Type      | Description                                                                    | Required | Example       |
| --------------- | --------- | ------------------------------------------------------------------------------ | -------- | ------------- |
| **`relation`**  | `object`  | **Client relationship object**.                                                | Yes      |               |
| → **`cuid`**    | `string`  | **Customer/client identifier**.                                                | Yes      | `cust_789xyz` |
| → **`isOwner`** | `boolean` | **Ownership permission**. `true` = full admin access, `false` = standard user. | Yes      | `true`        |

**Example Request Body:**

```json
{
  "relation": {
    "cuid": "cust_789xyz",
    "isOwner": true
  }
}
```

***

### **Response (200 OK)**

Returns the updated user object confirming the operation was successful.

#### **Response Fields**

**User Object (`item`)**

| Field          | Type      | Description                     | Example                |
| -------------- | --------- | ------------------------------- | ---------------------- |
| **`uuid`**     | `string`  | **Unique user identifier**.     | `user_abc123def`       |
| **`username`** | `string`  | **User's login name**.          | `john.smith`           |
| **`status`**   | `string`  | **Current user status**.        | `ACCEPT`               |
| **`is2fa`**    | `boolean` | **2FA enabled status**.         | `true`                 |
| **`createAt`** | `string`  | **Account creation timestamp**. | `2024-01-15T10:30:00Z` |
| **`updateAt`** | `string`  | **Last update timestamp**.      | `2024-03-20T14:22:00Z` |
| **`name`**     | `string`  | **User's full name**.           | `John Smith`           |
| **`comment`**  | `string`  | **Administrative comments**.    | `VIP customer`         |

**Example Response:**

```json
{
  "item": {
    "uuid": "user_abc123def",
    "username": "john.smith",
    "status": "ACCEPT",
    "is2fa": true,
    "createAt": "2024-01-15T10:30:00Z",
    "updateAt": "2024-03-20T14:22:00Z",
    "name": "John Smith",
    "comment": "VIP customer"
  }
}
```

> **Note:** The response shows basic user details. To verify the client relationship was successfully added, use the **Get User** endpoint which will include the `clients` array with all relationships.

***

### **Examples**

#### **Grant Owner Access to Client (cURL)**

```bash
curl --request PUT \
  --url https://stagep.tst-apidmndelss.com/v2/user/user_abc123def/relate-client \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer eyJhbGci...wNLGA' \
  --header 'Content-Type: application/json' \
  --data '{
    "relation": {
      "cuid": "cust_789xyz",
      "isOwner": true
    }
  }'
```

#### **Grant Standard User Access**

```bash
curl --request PUT \
  --url https://stagep.tst-apidmndelss.com/v2/user/user_456ghi/relate-client \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer eyJhbGci...wNLGA' \
  --header 'Content-Type: application/json' \
  --data '{
    "relation": {
      "cuid": "cust_123abc",
      "isOwner": false
    }
  }'
```

***

### **Error Responses**

1. **User Not Found**:

   ```json
   { "error": "User not found: user_invalid_id" }
   ```
2. **Customer Not Found**:

   ```json
   { "error": "Customer not found: cust_invalid_id" }
   ```
3. **Unauthorized**:

   ```json
   { "error": "Unauthorized" }
   ```
4. **Relationship Already Exists**:

   ```json
   { "error": "User already related to this customer" }
   ```

***

### **Notes**

#### **Permission Levels**

* **`isOwner: true`**: User has full administrative rights over the customer account
* **`isOwner: false`**: User has standard access with limited permissions

#### **Key Features**

* **Idempotent**: Calling multiple times with same parameters has the same effect
* **Overwrites**: Updates existing relationships if already present
* **Multiple Relationships**: Users can be linked to multiple customers

#### **Best Practices**

* Verify both user and customer exist before creating relationship
* Use **Get User** endpoint to confirm relationship was established
* Consider user's role and responsibilities when setting ownership
* Document relationship purposes in user comments if needed

**Common Use Cases**:

* Onboarding new users to customer accounts
* Promoting users to administrator roles
* Managing access across multiple client accounts
* Temporary access grants for support purposes

**Ownership Implications**:

* Owners can typically manage other users on the account
* Owners may have billing and configuration privileges
* Ownership often includes audit and reporting access

**Verification**:\
After binding a client, use the **Get User** endpoint to confirm the relationship:

```bash
curl --request GET \
  --url https://stagep.tst-apidmndelss.com/v2/user/user_abc123def \
  --header 'Authorization: Bearer eyJhbGci...wNLGA'
```

Look for the `clients` array in the response:

```json
"clients": [
  {
    "customerId": "cust_789xyz",
    "isOwner": true
  }
]
```

***

Request sample

```
Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOjE2NCwiZXhwIjoxNzYxNTcyNjY1LCJrZXkiOiI1Y2ZiOGZjN2RmYjk4ZjVkYmIyZTgwNTVkZWFhN2U2Zjk4MzEyYmE3Iiwib3RwX3ZlcmlmaWVkIjpmYWxzZX0.-SZ9Vc_BimN9juZElxhZeMQV5Hbb1WqUY2b8xwOSZLo
userId*: 158a190e-c4a9-4e6c-bf9b-4ef74ae345eb
```

```postman_json
{
  "customerId": "DoxdEEV-4IJq-zKeUYqrtqVDK",
  "isOwner": true
}
```

Response sample

```postman_json
{
  "item": {
    "userId": "5ff73da8-224e-44de-a235-2d7a76c3144c",
    "username": "test@delos.financial",
    "status": "ACCEPT",
    "is2fa": false,
    "createAt": "2024-12-12T15:47:23Z",
    "updateAt": "2025-09-01T06:56:28Z",
    "name": "Test",
    "comment": ""
  }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.delos.financial/users/bind-client.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.