Bind client

Establishes or updates a relationship between a user and a client/customer account. This endpoint links a user to a specific customer, defining their access level and permissions within that client ac

Endpoint

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

Link

Gateway APIstagep.tst-apidmndelss.com

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:

{
  "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:

{
  "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)

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

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:

   { "error": "User not found: user_invalid_id" }

2. Customer Not Found:

   { "error": "Customer not found: cust_invalid_id" }

3. Unauthorized:

   { "error": "Unauthorized" }

4. Relationship Already Exists:

   { "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:

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:

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

---

Request sample

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

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

Response sample

{
  "item": {
    "userId": "5ff73da8-224e-44de-a235-2d7a76c3144c",
    "username": "[email protected]",
    "status": "ACCEPT",
    "is2fa": false,
    "createAt": "2024-12-12T15:47:23Z",
    "updateAt": "2025-09-01T06:56:28Z",
    "name": "Test",
    "comment": ""
  }
}