Operation details
GET /v1/user-configs
List per-user stream defaults
- operationId
listUserConfigs- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：streams.read
Description (from the contract)
type must be stream. Tenant principals see only their own rows; platform principals see all rows in the selected scope.
Parameters
listUserConfigs Parameters| Name | In | Type | Required | Description |
|---|
X-Request-ID | header | string | No | Caller-stable request identity; invalid or absent values are replaced by middleware. |
|---|
type | query | string | Yes | — |
|---|
page | query | integer | No | — |
|---|
limit | query | integer | No | — |
|---|
search | query | string | No | — |
|---|
Responses
listUserConfigs Responses| Status | Description |
|---|
200 | Stable page ordered oldest first; display_id is the row ordinal. Fields：items: array<StreamUserConfig> total: integer(int64) page: integer limit: integer |
|---|
400 | Stable invalid request or validation error. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | The authenticated principal lacks the required permission or owner scope. |
|---|
500 | Internal operation failure without publication or activation claims. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list
POST /v1/user-configs
Create a per-user stream default
- operationId
createUserConfig- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：streams.manage
Description (from the contract)
The scope is global, or a forwarding group that must exist in the same scope. New forwards resolve these defaults when the field is omitted.
Parameters
createUserConfig Parameters| Name | In | Type | Required | Description |
|---|
X-Request-ID | header | string | No | Caller-stable request identity; invalid or absent values are replaced by middleware. |
|---|
Idempotency-Key | header | string | Yes | Reuse is accepted only for the exact same actor, operation, and normalized input. |
|---|
Request body
application/json · Required：Yes
createUserConfig Request body| Name | Type | Required | Description |
|---|
target_scope_id | string(uuid) | No | Required for platform principals; tenant principals may omit it or use their current scope. |
|---|
owner_id | string(uuid) | No | Required for platform principals; tenant principals may omit it or use their current user. |
|---|
setting_name | string: proxy_protocol / listen_protocol / balance_way | Yes | — |
|---|
setting_value | string | Yes | — |
|---|
scope_name | string: global / group | Yes | — |
|---|
group_id | string(uuid) | No | Required exactly when scope_name is group, and must exist in the same scope. |
|---|
Responses
createUserConfig Responses| Status | Description |
|---|
201 | Default committed, or an exact idempotent replay returned. Fields：id: string(uuid) display_id: string scope_id: string(uuid) owner: StreamOwner | null setting_name: string: proxy_protocol / listen_protocol / balance_way setting_value: string scope_name: string: global / group group: StreamGroupReference | null created_at: string(date-time) |
|---|
400 | Stable invalid request or validation error. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | The authenticated principal lacks the required permission or owner scope. |
|---|
409 | Revision, idempotency, name, or listener-port conflict. |
|---|
415 | Exactly one Content-Type field parsing as application/json is required. |
|---|
500 | Internal operation failure without publication or activation claims. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list
GET /v1/user-configs/effective
Resolve the stream defaults a new forward draft is prefilled with
- operationId
getEffectiveUserConfigs- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：streams.read
Description (from the contract)
type must be stream. The same resolution as creating a forward: the owner's global defaults, overridden by those of the given groups. Tenant principals resolve their own; platform principals must give target_scope_id and owner_id of a tenant member.
Parameters
getEffectiveUserConfigs Parameters| Name | In | Type | Required | Description |
|---|
X-Request-ID | header | string | No | Caller-stable request identity; invalid or absent values are replaced by middleware. |
|---|
type | query | string | Yes | — |
|---|
target_scope_id | query | string(uuid) | No | — |
|---|
owner_id | query | string(uuid) | No | — |
|---|
group_id | query | array<string(uuid)> | No | — |
|---|
Responses
getEffectiveUserConfigs Responses| Status | Description |
|---|
200 | Effective defaults. Fields：protocol: string: tcp / udp / null | null: tcp / udp / null proxy_protocol_inbound: boolean | null balance_way: string: rr / ip_hash / null | null: rr / ip_hash / null |
|---|
400 | Stable invalid request or validation error. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | The authenticated principal lacks the required permission or owner scope. |
|---|
500 | Internal operation failure without publication or activation claims. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list
DELETE /v1/user-configs/{id}
Delete a per-user stream default
- operationId
deleteUserConfig- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：streams.manage
Parameters
deleteUserConfig Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | Exact per-user stream default identity. |
|---|
X-Request-ID | header | string | No | Caller-stable request identity; invalid or absent values are replaced by middleware. |
|---|
Idempotency-Key | header | string | Yes | Reuse is accepted only for the exact same actor, operation, and normalized input. |
|---|
Responses
deleteUserConfig Responses| Status | Description |
|---|
204 | Default deleted. |
|---|
400 | Stable invalid request or validation error. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | The authenticated principal lacks the required permission or owner scope. |
|---|
404 | No visible stream matches the exact immutable stream identity. |
|---|
409 | Revision, idempotency, name, or listener-port conflict. |
|---|
500 | Internal operation failure without publication or activation claims. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list