Team Management
The Team Management endpoints allow customer account owners and admins to manage team members with role-based access control.
Role Hierarchy
| Role | Level | Description |
|---|---|---|
| Owner | 0 | Full account control, can delete customer and transfer ownership |
| Admin | 1 | Can manage team members and view limits |
| User | 2 | Read-only access to customer information and limits |
Add Member
Add a new team member to the customer account.
Endpoint: https://apis.threatwinds.com/api/billing/v1/customer/member
Method: POST
Parameters
Headers
| Header | Type | Required | Description |
|---|---|---|---|
| Authorization | string | Optional* | Bearer token for session authentication |
| api-key | string | Optional* | API key for key-based authentication |
| api-secret | string | Optional* | API secret for key-based authentication |
Note: You must use either Authorization header OR API key/secret combination.
Request Body
{
"userID": "660e8400-e29b-41d4-a716-446655440000",
"role": 2
}
| Parameter | Type | Required | Description |
|---|---|---|---|
| userID | string (UUID) | Yes | User unique identifier |
| role | integer | Yes | Role level: 0=Owner, 1=Admin, 2=User |
Required Roles
Required role: owner or admin
Request
To add a team member, use a POST request:
curl -X 'POST' \
'https://apis.threatwinds.com/api/billing/v1/customer/member' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-d '{
"userID": "660e8400-e29b-41d4-a716-446655440000",
"role": 2
}'
Or using API key and secret:
curl -X 'POST' \
'https://apis.threatwinds.com/api/billing/v1/customer/member' \
-H 'accept: application/json' \
-H 'api-key: your-api-key' \
-H 'api-secret: your-api-secret' \
-H 'Content-Type: application/json' \
-d '{
"userID": "660e8400-e29b-41d4-a716-446655440000",
"role": 2
}'
Response
Success Response (201 Created)
{
"message": "acknowledged"
}
Business Logic
- Caller must be ROLE_ADMIN or ROLE_OWNER
- Cannot assign role higher than caller’s role
- Cannot directly assign ROLE_OWNER (must use transfer ownership endpoint)
- New member must not already be part of a customer
- Validates tier member limits before adding
- Increments team member count and checks subscription tier allows it
Error Codes
| Status Code | Description | Possible Cause |
|---|---|---|
| 201 | Created | Member added successfully |
| 400 | Bad Request | Invalid JSON, user already member, cannot assign owner role |
| 401 | Unauthorized | Missing or invalid authentication |
| 402 | Payment Required | Subscription tier member limit exceeded |
| 403 | Forbidden | Not authorized, trying to assign higher role than caller has |
Update Member
Update a team member’s role.
Endpoint: https://apis.threatwinds.com/api/billing/v1/customer/member
Method: PUT
Parameters
Headers
| Header | Type | Required | Description |
|---|---|---|---|
| Authorization | string | Optional* | Bearer token for session authentication |
| api-key | string | Optional* | API key for key-based authentication |
| api-secret | string | Optional* | API secret for key-based authentication |
Note: You must use either Authorization header OR API key/secret combination.
Request Body
{
"userID": "660e8400-e29b-41d4-a716-446655440000",
"role": 1
}
| Parameter | Type | Required | Description |
|---|---|---|---|
| userID | string (UUID) | Yes | User unique identifier |
| role | integer | Yes | New role level: 0=Owner, 1=Admin, 2=User |
Required Roles
Required role: owner or admin
Request
To update a member’s role, use a PUT request:
curl -X 'PUT' \
'https://apis.threatwinds.com/api/billing/v1/customer/member' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-d '{
"userID": "660e8400-e29b-41d4-a716-446655440000",
"role": 1
}'
Or using API key and secret:
curl -X 'PUT' \
'https://apis.threatwinds.com/api/billing/v1/customer/member' \
-H 'accept: application/json' \
-H 'api-key: your-api-key' \
-H 'api-secret: your-api-secret' \
-H 'Content-Type: application/json' \
-d '{
"userID": "660e8400-e29b-41d4-a716-446655440000",
"role": 1
}'
Response
Success Response (204 No Content)
{
"message": "acknowledged"
}
Business Logic
- Caller must be ROLE_ADMIN or ROLE_OWNER
- Cannot update own role
- Cannot assign role higher than caller’s role
- If demoting from ROLE_OWNER, validates there’s at least one other owner
- Member must be in same customer account
Error Codes
| Status Code | Description | Possible Cause |
|---|---|---|
| 204 | No Content | Member role updated successfully |
| 400 | Bad Request | Invalid JSON, trying to update own role, user not member |
| 401 | Unauthorized | Missing or invalid authentication |
| 403 | Forbidden | Not authorized, trying to assign higher role than caller has |
| 412 | Precondition Failed | Cannot demote last owner |
Delete Member
Remove a team member from the customer account.
Endpoint: https://apis.threatwinds.com/api/billing/v1/customer/member/{userID}
Method: DELETE
Parameters
Headers
| Header | Type | Required | Description |
|---|---|---|---|
| Authorization | string | Optional* | Bearer token for session authentication |
| api-key | string | Optional* | API key for key-based authentication |
| api-secret | string | Optional* | API secret for key-based authentication |
Note: You must use either Authorization header OR API key/secret combination.
Path Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| userID | string (UUID) | Yes | User unique identifier | 660e8400-e29b-41d4-a716-446655440000 |
Required Roles
Required role: owner or admin
Request
To remove a team member, use a DELETE request:
curl -X 'DELETE' \
'https://apis.threatwinds.com/api/billing/v1/customer/member/660e8400-e29b-41d4-a716-446655440000' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <token>'
Or using API key and secret:
curl -X 'DELETE' \
'https://apis.threatwinds.com/api/billing/v1/customer/member/660e8400-e29b-41d4-a716-446655440000' \
-H 'accept: application/json' \
-H 'api-key: your-api-key' \
-H 'api-secret: your-api-secret'
Response
Success Response (204 No Content)
{
"message": "acknowledged"
}
Business Logic
- Caller must be ROLE_ADMIN or ROLE_OWNER
- Cannot delete member with higher role than caller
- If deleting ROLE_OWNER, validates there’s another owner
- Member must be in same customer account
- Decrements team member count
Error Codes
| Status Code | Description | Possible Cause |
|---|---|---|
| 204 | No Content | Member removed successfully |
| 400 | Bad Request | Invalid UUID path parameter, user not member |
| 401 | Unauthorized | Missing or invalid authentication |
| 403 | Forbidden | Not authorized, trying to delete member with higher role |
| 412 | Precondition Failed | Cannot delete last owner |
Get Members
List all team members for the customer account with pagination.
Endpoint: https://apis.threatwinds.com/api/billing/v1/customer/members
Method: GET
Parameters
Headers
| Header | Type | Required | Description |
|---|---|---|---|
| Authorization | string | Optional* | Bearer token for session authentication |
| api-key | string | Optional* | API key for key-based authentication |
| api-secret | string | Optional* | API secret for key-based authentication |
Note: You must use either Authorization header OR API key/secret combination.
Query Parameters
| Parameter | Type | Required | Description | Default | Constraints |
|---|---|---|---|---|---|
| page | integer | No | Page number | 1 | Minimum: 1 |
| pageSize | integer | No | Items per page | 20 | Maximum: 100 |
Required Roles
Required role: owner or admin
Request
To list team members, use a GET request:
curl -X 'GET' \
'https://apis.threatwinds.com/api/billing/v1/customer/members?page=1&pageSize=20' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <token>'
Or using API key and secret:
curl -X 'GET' \
'https://apis.threatwinds.com/api/billing/v1/customer/members?page=1&pageSize=20' \
-H 'accept: application/json' \
-H 'api-key: your-api-key' \
-H 'api-secret: your-api-secret'
Response
Success Response (200 OK)
{
"members": [
{
"roleID": "770e8400-e29b-41d4-a716-446655440000",
"userID": "660e8400-e29b-41d4-a716-446655440000",
"role": 0
},
{
"roleID": "880e8400-e29b-41d4-a716-446655440000",
"userID": "990e8400-e29b-41d4-a716-446655440000",
"role": 1
}
],
"pagination": {
"page": 1,
"pageSize": 20,
"totalCount": 2,
"totalPages": 1,
"hasNext": false,
"hasPrev": false
}
}
Response Schema
| Field | Type | Description |
|---|---|---|
| members | array | List of team members |
| members[].roleID | string (UUID) | Role assignment unique identifier |
| members[].userID | string (UUID) | User unique identifier |
| members[].role | integer | Role level: 0=Owner, 1=Admin, 2=User |
| pagination | object | Pagination metadata |
| pagination.page | integer | Current page number |
| pagination.pageSize | integer | Items per page |
| pagination.totalCount | integer | Total number of members |
| pagination.totalPages | integer | Total number of pages |
| pagination.hasNext | boolean | Whether next page exists |
| pagination.hasPrev | boolean | Whether previous page exists |
Error Codes
| Status Code | Description | Possible Cause |
|---|---|---|
| 200 | OK | Request successful |
| 400 | Bad Request | Invalid query parameters |
| 401 | Unauthorized | Missing or invalid authentication |
| 403 | Forbidden | Not authorized (requires owner or admin role) |
Transfer Ownership
Transfer account ownership to another existing team member. The current owner is demoted to admin.
Endpoint: https://apis.threatwinds.com/api/billing/v1/customer/transfer-ownership
Method: POST
Parameters
Headers
| Header | Type | Required | Description |
|---|---|---|---|
| Authorization | string | Optional* | Bearer token for session authentication |
| api-key | string | Optional* | API key for key-based authentication |
| api-secret | string | Optional* | API secret for key-based authentication |
Note: You must use either Authorization header OR API key/secret combination.
Request Body
{
"newOwnerUserID": "660e8400-e29b-41d4-a716-446655440000"
}
| Parameter | Type | Required | Description |
|---|---|---|---|
| newOwnerUserID | string (UUID) | Yes | User ID of new owner |
Required Roles
Required role: owner
This endpoint can only be used by the current account owner.
Request
To transfer ownership, use a POST request:
curl -X 'POST' \
'https://apis.threatwinds.com/api/billing/v1/customer/transfer-ownership' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-d '{
"newOwnerUserID": "660e8400-e29b-41d4-a716-446655440000"
}'
Or using API key and secret:
curl -X 'POST' \
'https://apis.threatwinds.com/api/billing/v1/customer/transfer-ownership' \
-H 'accept: application/json' \
-H 'api-key: your-api-key' \
-H 'api-secret: your-api-secret' \
-H 'Content-Type: application/json' \
-d '{
"newOwnerUserID": "660e8400-e29b-41d4-a716-446655440000"
}'
Response
Success Response (200 OK)
{
"message": "acknowledged"
}
Business Logic
- Current user must be ROLE_OWNER
- New owner must already be a member of the same customer
- Cannot transfer to self
- Current owner is demoted to ROLE_ADMIN (retains access)
- New owner is promoted to ROLE_OWNER
- Validates customer has an owner after transfer
Error Codes
| Status Code | Description | Possible Cause |
|---|---|---|
| 200 | OK | Ownership transferred successfully |
| 400 | Bad Request | Invalid JSON, trying to transfer to self |
| 401 | Unauthorized | Missing or invalid authentication |
| 403 | Forbidden | Not authorized, caller not owner |
| 404 | Not Found | Customer not found, new owner not a member |
| 412 | Precondition Failed | Business logic validation failed |