用户组与访问授权

维护用户组、组成员和访问授权；写操作需要 `full` 令牌。本页完整列出 14 个受支持操作的请求与响应契约。

路径均相对于 https://<nsd-host>。先设置 NSD_BASE_URL=https://<nsd-host>/api/v1 和 NSD_TOKEN；示例 ID 与数据均为虚构值。

列出用户组

GET/api/v1/groupsread-only / full

参数

名称	位置	类型	必填	说明
`cursor`	query	`string \| null`	否	Opaque cursor — the last id of the previous page. Absent on page 1.
`limit`	query	`integer \| null`	否	Requested page size; clamped to `1..=MAX_LIMIT`.

请求示例

curl --silent --show-error --fail-with-body -X GET \
  "$NSD_BASE_URL/groups?limit=100" \
  -H "Authorization: Bearer $NSD_TOKEN" \
  -H 'Accept: application/json'

响应状态

状态	含义	响应结构
`200`	Paginated list of groups in the caller's realm	`ListGroupsResponse`
`401`	缺少或无效的 Bearer 令牌。	`ProblemDetails`

200 响应

字段	类型	必有	说明
`items`	`array<GroupView>`	是	Groups in this page.
`items[].auto_members`	`string \| null`	否	Automatic membership rule for system groups, or `null`.
`items[].created_at`	`string`	是	Creation timestamp (RFC 3339 UTC).
`items[].created_by`	`string`	是	Actor label that created the group.
`items[].description`	`string \| null`	否	Optional description.
`items[].id`	`string`	是	Group ULID.
`items[].kind`	`string`	是	Group kind (`static` or `system`).
`items[].member_count`	`integer`	是	Effective member count.
`items[].name`	`string`	是	Display name.
`items[].realm_id`	`string`	是	Owning realm ULID.
`items[].slug`	`string`	是	URL-safe slug.
`next_cursor`	`string \| null`	否	Cursor for the next page, or `null` when there is no next page.

{
  "items": [
    {
      "auto_members": "example",
      "created_at": "2026-09-09T10:00:00Z",
      "created_by": "example",
      "description": "用于生产自动化",
      "id": "01K4EXAMPLE0000000000000",
      "kind": "static",
      "member_count": 1,
      "name": "示例资源",
      "realm_id": "01K4EXAMPLE0000000000000",
      "slug": "example"
    }
  ],
  "next_cursor": "example"
}

错误响应均使用 Problem Details；调用方应判断 HTTP 状态和稳定的 code，不要解析 detail 文案。

创建用户组

POST/api/v1/groupsfull

请求体

字段	类型	必填	说明
`description`	`string \| null`	否	Optional description.
`name`	`string`	是	Display name.

request.json

{
  "description": "用于生产自动化",
  "name": "示例资源"
}

请求示例

curl --silent --show-error --fail-with-body -X POST \
  "$NSD_BASE_URL/groups" \
  -H "Authorization: Bearer $NSD_TOKEN" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data @request.json

响应状态

状态	含义	响应结构
`201`	用户组已创建。	`GroupView`
`401`	缺少或无效的 Bearer 令牌。	`ProblemDetails`

201 响应

字段	类型	必有	说明
`auto_members`	`string \| null`	否	Automatic membership rule for system groups, or `null`.
`created_at`	`string`	是	Creation timestamp (RFC 3339 UTC).
`created_by`	`string`	是	Actor label that created the group.
`description`	`string \| null`	否	Optional description.
`id`	`string`	是	Group ULID.
`kind`	`string`	是	Group kind (`static` or `system`).
`member_count`	`integer`	是	Effective member count.
`name`	`string`	是	Display name.
`realm_id`	`string`	是	Owning realm ULID.
`slug`	`string`	是	URL-safe slug.

{
  "auto_members": "example",
  "created_at": "2026-09-09T10:00:00Z",
  "created_by": "example",
  "description": "用于生产自动化",
  "id": "01K4EXAMPLE0000000000000",
  "kind": "static",
  "member_count": 1,
  "name": "示例资源",
  "realm_id": "01K4EXAMPLE0000000000000",
  "slug": "example"
}

错误响应均使用 Problem Details；调用方应判断 HTTP 状态和稳定的 code，不要解析 detail 文案。

读取用户组

GET/api/v1/groups/{id}read-only / full

参数

名称	位置	类型	必填	说明
`id`	path	`string`	是	Group ULID

请求示例

curl --silent --show-error --fail-with-body -X GET \
  "$NSD_BASE_URL/groups/${GROUP_ID}" \
  -H "Authorization: Bearer $NSD_TOKEN" \
  -H 'Accept: application/json'

响应状态

状态	含义	响应结构
`200`	The group with member count	`GroupView`
`401`	缺少或无效的 Bearer 令牌。	`ProblemDetails`
`404`	当前 Network 中不存在该用户组。	`ProblemDetails`

200 响应

字段	类型	必有	说明
`auto_members`	`string \| null`	否	Automatic membership rule for system groups, or `null`.
`created_at`	`string`	是	Creation timestamp (RFC 3339 UTC).
`created_by`	`string`	是	Actor label that created the group.
`description`	`string \| null`	否	Optional description.
`id`	`string`	是	Group ULID.
`kind`	`string`	是	Group kind (`static` or `system`).
`member_count`	`integer`	是	Effective member count.
`name`	`string`	是	Display name.
`realm_id`	`string`	是	Owning realm ULID.
`slug`	`string`	是	URL-safe slug.

{
  "auto_members": "example",
  "created_at": "2026-09-09T10:00:00Z",
  "created_by": "example",
  "description": "用于生产自动化",
  "id": "01K4EXAMPLE0000000000000",
  "kind": "static",
  "member_count": 1,
  "name": "示例资源",
  "realm_id": "01K4EXAMPLE0000000000000",
  "slug": "example"
}

错误响应均使用 Problem Details；调用方应判断 HTTP 状态和稳定的 code，不要解析 detail 文案。

修改用户组

PATCH/api/v1/groups/{id}full

参数

名称	位置	类型	必填	说明
`id`	path	`string`	是	Group ULID

请求体

字段	类型	必填	说明
`description`	`string \| null`	否	New description, or `null` to clear.
`name`	`string \| null`	否	New display name.

request.json

{
  "description": "用于生产自动化",
  "name": "示例资源"
}

请求示例

curl --silent --show-error --fail-with-body -X PATCH \
  "$NSD_BASE_URL/groups/${GROUP_ID}" \
  -H "Authorization: Bearer $NSD_TOKEN" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data @request.json

响应状态

状态	含义	响应结构
`200`	用户组已更新。	`GroupView`
`401`	缺少或无效的 Bearer 令牌。	`ProblemDetails`
`403`	系统用户组为只读，不能修改。	`ProblemDetails`
`404`	当前 Network 中不存在该用户组。	`ProblemDetails`

200 响应

字段	类型	必有	说明
`auto_members`	`string \| null`	否	Automatic membership rule for system groups, or `null`.
`created_at`	`string`	是	Creation timestamp (RFC 3339 UTC).
`created_by`	`string`	是	Actor label that created the group.
`description`	`string \| null`	否	Optional description.
`id`	`string`	是	Group ULID.
`kind`	`string`	是	Group kind (`static` or `system`).
`member_count`	`integer`	是	Effective member count.
`name`	`string`	是	Display name.
`realm_id`	`string`	是	Owning realm ULID.
`slug`	`string`	是	URL-safe slug.

{
  "auto_members": "example",
  "created_at": "2026-09-09T10:00:00Z",
  "created_by": "example",
  "description": "用于生产自动化",
  "id": "01K4EXAMPLE0000000000000",
  "kind": "static",
  "member_count": 1,
  "name": "示例资源",
  "realm_id": "01K4EXAMPLE0000000000000",
  "slug": "example"
}

错误响应均使用 Problem Details；调用方应判断 HTTP 状态和稳定的 code，不要解析 detail 文案。

删除用户组

DELETE/api/v1/groups/{id}full

参数

名称	位置	类型	必填	说明
`id`	path	`string`	是	Group ULID

请求示例

curl --silent --show-error --fail-with-body -X DELETE \
  "$NSD_BASE_URL/groups/${GROUP_ID}" \
  -H "Authorization: Bearer $NSD_TOKEN" \
  -H 'Accept: application/json'

响应状态

状态	含义	响应结构
`204`	用户组已删除。	`—`
`401`	缺少或无效的 Bearer 令牌。	`ProblemDetails`
`403`	系统用户组为只读，不能修改。	`ProblemDetails`
`404`	当前 Network 中不存在该用户组。	`ProblemDetails`

204 响应

成功，无响应体。

错误响应均使用 Problem Details；调用方应判断 HTTP 状态和稳定的 code，不要解析 detail 文案。

列出组成员

GET/api/v1/groups/{id}/membersread-only / full

参数

名称	位置	类型	必填	说明
`id`	path	`string`	是	Group ULID

请求示例

curl --silent --show-error --fail-with-body -X GET \
  "$NSD_BASE_URL/groups/${GROUP_ID}/members" \
  -H "Authorization: Bearer $NSD_TOKEN" \
  -H 'Accept: application/json'

响应状态

状态	含义	响应结构
`200`	The group's member users	`array<AdminUserView>`
`401`	缺少或无效的 Bearer 令牌。	`ProblemDetails`
`404`	当前 Network 中不存在该用户组。	`ProblemDetails`

200 响应

字段	类型	必有	说明
`[].created_at`	`string`	是	Creation timestamp (RFC 3339 UTC).
`[].disabled`	`boolean`	是	Whether the user is disabled.
`[].email`	`string`	是	Email address.
`[].id`	`string`	是	User ULID.
`[].last_login_at`	`string \| null`	否	Last login timestamp (RFC 3339 UTC), or `null`.
`[].mfa_enabled`	`boolean`	是	Whether MFA is enabled.
`[].name`	`string`	是	Display name.
`[].realm_id`	`string`	是	Owning realm ULID.
`[].role`	`string`	是	Role (`admin` or `member`).

[
  {
    "created_at": "2026-09-09T10:00:00Z",
    "disabled": false,
    "email": "operator@example.com",
    "id": "01K4EXAMPLE0000000000000",
    "last_login_at": "2026-09-09T10:00:00Z",
    "mfa_enabled": false,
    "name": "示例资源",
    "realm_id": "01K4EXAMPLE0000000000000",
    "role": "admin"
  }
]

错误响应均使用 Problem Details；调用方应判断 HTTP 状态和稳定的 code，不要解析 detail 文案。

添加组成员

POST/api/v1/groups/{id}/membersfull

参数

名称	位置	类型	必填	说明
`id`	path	`string`	是	Group ULID

请求体

字段	类型	必填	说明
`user_id`	`string`	是	User ULID to add.

request.json

{
  "user_id": "01K4USER000000000000000000"
}

请求示例

curl --silent --show-error --fail-with-body -X POST \
  "$NSD_BASE_URL/groups/${GROUP_ID}/members" \
  -H "Authorization: Bearer $NSD_TOKEN" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data @request.json

响应状态

状态	含义	响应结构
`200`	Member added; returns the updated member list	`array<AdminUserView>`
`400`	Missing user_id, or user is not in this realm	`ProblemDetails`
`401`	缺少或无效的 Bearer 令牌。	`ProblemDetails`
`403`	系统用户组为只读，不能修改。	`ProblemDetails`
`404`	当前 Network 中不存在该用户组。	`ProblemDetails`

200 响应

字段	类型	必有	说明
`[].created_at`	`string`	是	Creation timestamp (RFC 3339 UTC).
`[].disabled`	`boolean`	是	Whether the user is disabled.
`[].email`	`string`	是	Email address.
`[].id`	`string`	是	User ULID.
`[].last_login_at`	`string \| null`	否	Last login timestamp (RFC 3339 UTC), or `null`.
`[].mfa_enabled`	`boolean`	是	Whether MFA is enabled.
`[].name`	`string`	是	Display name.
`[].realm_id`	`string`	是	Owning realm ULID.
`[].role`	`string`	是	Role (`admin` or `member`).

[
  {
    "created_at": "2026-09-09T10:00:00Z",
    "disabled": false,
    "email": "operator@example.com",
    "id": "01K4EXAMPLE0000000000000",
    "last_login_at": "2026-09-09T10:00:00Z",
    "mfa_enabled": false,
    "name": "示例资源",
    "realm_id": "01K4EXAMPLE0000000000000",
    "role": "admin"
  }
]

错误响应均使用 Problem Details；调用方应判断 HTTP 状态和稳定的 code，不要解析 detail 文案。

移除组成员

DELETE/api/v1/groups/{id}/members/{user_id}full

参数

名称	位置	类型	必填	说明
`id`	path	`string`	是	Group ULID
`user_id`	path	`string`	是	User ULID to remove

请求示例

curl --silent --show-error --fail-with-body -X DELETE \
  "$NSD_BASE_URL/groups/${GROUP_ID}/members/${USER_ID}" \
  -H "Authorization: Bearer $NSD_TOKEN" \
  -H 'Accept: application/json'

响应状态

状态	含义	响应结构
`204`	组成员已移除。	`—`
`401`	缺少或无效的 Bearer 令牌。	`ProblemDetails`
`403`	系统用户组为只读，不能修改。	`ProblemDetails`
`404`	当前 Network 中不存在该用户组。	`ProblemDetails`

204 响应

成功，无响应体。

错误响应均使用 Problem Details；调用方应判断 HTTP 状态和稳定的 code，不要解析 detail 文案。

列出访问授权

GET/api/v1/policiesread-only / full

参数

名称	位置	类型	必填	说明
`cursor`	query	`string \| null`	否	Cursor pagination: last policy id returned by the previous page.
`limit`	query	`integer \| null`	否	Requested page size (clamped by the shared pagination contract).
`q`	query	`string \| null`	否	Case-insensitive literal substring search over policy name and stable id.

请求示例

curl --silent --show-error --fail-with-body -X GET \
  "$NSD_BASE_URL/policies?limit=100" \
  -H "Authorization: Bearer $NSD_TOKEN" \
  -H 'Accept: application/json'

响应状态

状态	含义	响应结构
`200`	Paginated list of policies in the caller's realm	`ListPoliciesResponse`
`400`	Search query exceeds 128 characters	`ProblemDetails`
`401`	缺少或无效的 Bearer 令牌。	`ProblemDetails`

200 响应

字段	类型	必有	说明
`items`	`array<PolicyView>`	是	Policies in this page.
`items[].action`	`string`	是	Effect (currently always `allow`).
`items[].compile_error`	`string \| null`	否	Why the Grant is dropped. Absent while `compile_status` is `compiled`.
`items[].compile_error_code`	`string \| null`	否	Stable token naming the same rejection as `compile_error`, for alerting that must not depend on wording. Absent while `compile_status` is `compiled`.
`items[].compile_status`	`PolicyCompileStatusView`	是	Whether the grant can take effect. A rejected grant does not allow access even when enabled is true; inspect compile_error and compile_error_code.
`items[].conditions`	`object`	是	Free-form conditions object.
`items[].created_at`	`string`	是	Creation time (RFC 3339 UTC).
`items[].created_by`	`string`	是	Label of the actor who created it.
`items[].enabled`	`boolean`	是	Whether the policy is active.
`items[].enforced_at`	`string`	是	Enforcement point (`node` \| `gateway`).
`items[].id`	`string`	是	Policy ULID.
`items[].name`	`string`	是	Display name.
`items[].realm_id`	`string`	是	Owning realm ULID.
`items[].resource`	`object`	是	What the policy grants access to (`{ type, … }`).
`items[].subject`	`object`	是	Who the policy applies to (`{ type, … }`).
`items[].version`	`integer`	是	Monotonic version, bumped on each update.
`next_cursor`	`string \| null`	否	Cursor for the next page, or `null` when there is no next page.

{
  "items": [
    {
      "action": "allow",
      "compile_error": "example",
      "compile_error_code": "example",
      "compile_status": {},
      "conditions": {},
      "created_at": "2026-09-09T10:00:00Z",
      "created_by": "example",
      "enabled": true,
      "enforced_at": "2026-09-09T10:00:00Z",
      "id": "01K4EXAMPLE0000000000000",
      "name": "示例资源",
      "realm_id": "01K4EXAMPLE0000000000000",
      "resource": {
        "type": "service",
        "service_id": "01K4SERVICE00000000000000"
      },
      "subject": {
        "type": "user",
        "user_id": "01K4USER000000000000000000"
      },
      "version": 1
    }
  ],
  "next_cursor": "example"
}

错误响应均使用 Problem Details；调用方应判断 HTTP 状态和稳定的 code，不要解析 detail 文案。

创建访问授权

POST/api/v1/policiesfull

请求体

字段	类型	必填	说明
`conditions`	`object`	否	Free-form conditions object.
`enabled`	`boolean \| null`	否	Whether the policy starts enabled (defaults to true).
`enforced_at`	`string \| null`	否	Deprecated compatibility hint. NSD derives the enforcement point from the policy subject and rejects a conflicting value.
`name`	`string`	是	Display name.
`resource`	`object`	否	Resource object `{ type, … }` (defaults to "Everything").
`subject`	`object`	否	Subject object `{ type, … }` (defaults to "Everyone").

request.json

{
  "conditions": {},
  "enabled": true,
  "enforced_at": "2026-09-09T10:00:00Z",
  "name": "示例资源",
  "resource": {
    "type": "service",
    "service_id": "01K4SERVICE00000000000000"
  },
  "subject": {
    "type": "user",
    "user_id": "01K4USER000000000000000000"
  }
}

请求示例

curl --silent --show-error --fail-with-body -X POST \
  "$NSD_BASE_URL/policies" \
  -H "Authorization: Bearer $NSD_TOKEN" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data @request.json

响应状态

状态	含义	响应结构
`201`	Created policy with distribution summary	`PolicyMutationResponse`
`400`	主体无效，或主体/资源不属于当前 Network。	`ProblemDetails`
`401`	缺少或无效的 Bearer 令牌。	`ProblemDetails`
`409`	OIDC 提供方与同一公网入口上的另一条访问授权冲突。	`ProblemDetails`

201 响应

字段	类型	必有	说明
`distribution`	`DistributionSummary`	是	Config-distribution summary for the realm.
`distribution.failed`	`integer`	是	Distribution failures (always 0 in the in-process path today).
`distribution.gateways`	`integer`	是	Gateways in the realm config was (re)distributed to.
`distribution.sites`	`integer`	是	Sites in the realm.
`policy`	`PolicyView`	是	The created/updated policy.
`policy.action`	`string`	是	Effect (currently always `allow`).
`policy.compile_error`	`string \| null`	否	Why the Grant is dropped. Absent while `compile_status` is `compiled`.
`policy.compile_error_code`	`string \| null`	否	Stable token naming the same rejection as `compile_error`, for alerting that must not depend on wording. Absent while `compile_status` is `compiled`.
`policy.compile_status`	`PolicyCompileStatusView`	是	Whether the grant can take effect. A rejected grant does not allow access even when enabled is true; inspect compile_error and compile_error_code.
`policy.conditions`	`object`	是	Free-form conditions object.
`policy.created_at`	`string`	是	Creation time (RFC 3339 UTC).
`policy.created_by`	`string`	是	Label of the actor who created it.
`policy.enabled`	`boolean`	是	Whether the policy is active.
`policy.enforced_at`	`string`	是	Enforcement point (`node` \| `gateway`).
`policy.id`	`string`	是	Policy ULID.
`policy.name`	`string`	是	Display name.
`policy.realm_id`	`string`	是	Owning realm ULID.
`policy.resource`	`object`	是	What the policy grants access to (`{ type, … }`).
`policy.subject`	`object`	是	Who the policy applies to (`{ type, … }`).
`policy.version`	`integer`	是	Monotonic version, bumped on each update.

{
  "distribution": {
    "failed": 1,
    "gateways": 1,
    "sites": 1
  },
  "policy": {
    "action": "allow",
    "compile_error": "example",
    "compile_error_code": "example",
    "compile_status": "compiled",
    "conditions": {},
    "created_at": "2026-09-09T10:00:00Z",
    "created_by": "example",
    "enabled": true,
    "enforced_at": "2026-09-09T10:00:00Z",
    "id": "01K4EXAMPLE0000000000000",
    "name": "示例资源",
    "realm_id": "01K4EXAMPLE0000000000000",
    "resource": {
      "type": "service",
      "service_id": "01K4SERVICE00000000000000"
    },
    "subject": {
      "type": "user",
      "user_id": "01K4USER000000000000000000"
    },
    "version": 1
  }
}

错误响应均使用 Problem Details；调用方应判断 HTTP 状态和稳定的 code，不要解析 detail 文案。

批量创建访问授权

POST/api/v1/policies/batchfull

请求体

字段	类型	必填	说明
`policies`	`array<CreatePolicyRequest>`	是	Complete policy rows to create (2–100).
`policies[].conditions`	`object`	否	Free-form conditions object.
`policies[].enabled`	`boolean \| null`	否	Whether the policy starts enabled (defaults to true).
`policies[].enforced_at`	`string \| null`	否	Deprecated compatibility hint. NSD derives the enforcement point from the policy subject and rejects a conflicting value.
`policies[].name`	`string`	是	Display name.
`policies[].resource`	`object`	否	Resource object `{ type, … }` (defaults to "Everything").
`policies[].subject`	`object`	否	Subject object `{ type, … }` (defaults to "Everyone").

request.json

{
  "policies": [
    {
      "conditions": {},
      "enabled": true,
      "enforced_at": "2026-09-09T10:00:00Z",
      "name": "示例资源",
      "resource": {
        "type": "service",
        "service_id": "01K4SERVICE00000000000000"
      },
      "subject": {
        "type": "user",
        "user_id": "01K4USER000000000000000000"
      }
    }
  ]
}

请求示例

curl --silent --show-error --fail-with-body -X POST \
  "$NSD_BASE_URL/policies/batch" \
  -H "Authorization: Bearer $NSD_TOKEN" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data @request.json

响应状态

状态	含义	响应结构
`201`	Created policies with one distribution update	`PolicyBatchMutationResponse`
`400`	批次或其中的访问授权无效。	`ProblemDetails`
`401`	缺少或无效的 Bearer 令牌。	`ProblemDetails`
`409`	启用访问授权审批时不能批量创建。	`ProblemDetails`

201 响应

字段	类型	必有	说明
`distribution`	`DistributionSummary`	是	Config-distribution summary for the realm.
`distribution.failed`	`integer`	是	Distribution failures (always 0 in the in-process path today).
`distribution.gateways`	`integer`	是	Gateways in the realm config was (re)distributed to.
`distribution.sites`	`integer`	是	Sites in the realm.
`policies`	`array<PolicyView>`	是	Policies created by the transaction.
`policies[].action`	`string`	是	Effect (currently always `allow`).
`policies[].compile_error`	`string \| null`	否	Why the Grant is dropped. Absent while `compile_status` is `compiled`.
`policies[].compile_error_code`	`string \| null`	否	Stable token naming the same rejection as `compile_error`, for alerting that must not depend on wording. Absent while `compile_status` is `compiled`.
`policies[].compile_status`	`PolicyCompileStatusView`	是	Whether the grant can take effect. A rejected grant does not allow access even when enabled is true; inspect compile_error and compile_error_code.
`policies[].conditions`	`object`	是	Free-form conditions object.
`policies[].created_at`	`string`	是	Creation time (RFC 3339 UTC).
`policies[].created_by`	`string`	是	Label of the actor who created it.
`policies[].enabled`	`boolean`	是	Whether the policy is active.
`policies[].enforced_at`	`string`	是	Enforcement point (`node` \| `gateway`).
`policies[].id`	`string`	是	Policy ULID.
`policies[].name`	`string`	是	Display name.
`policies[].realm_id`	`string`	是	Owning realm ULID.
`policies[].resource`	`object`	是	What the policy grants access to (`{ type, … }`).
`policies[].subject`	`object`	是	Who the policy applies to (`{ type, … }`).
`policies[].version`	`integer`	是	Monotonic version, bumped on each update.

{
  "distribution": {
    "failed": 1,
    "gateways": 1,
    "sites": 1
  },
  "policies": [
    {
      "action": "allow",
      "compile_error": "example",
      "compile_error_code": "example",
      "compile_status": {},
      "conditions": {},
      "created_at": "2026-09-09T10:00:00Z",
      "created_by": "example",
      "enabled": true,
      "enforced_at": "2026-09-09T10:00:00Z",
      "id": "01K4EXAMPLE0000000000000",
      "name": "示例资源",
      "realm_id": "01K4EXAMPLE0000000000000",
      "resource": {
        "type": "service",
        "service_id": "01K4SERVICE00000000000000"
      },
      "subject": {
        "type": "user",
        "user_id": "01K4USER000000000000000000"
      },
      "version": 1
    }
  ]
}

错误响应均使用 Problem Details；调用方应判断 HTTP 状态和稳定的 code，不要解析 detail 文案。

读取访问授权

GET/api/v1/policies/{id}read-only / full

参数

名称	位置	类型	必填	说明
`id`	path	`string`	是	Policy ULID

请求示例

curl --silent --show-error --fail-with-body -X GET \
  "$NSD_BASE_URL/policies/${POLICY_ID}" \
  -H "Authorization: Bearer $NSD_TOKEN" \
  -H 'Accept: application/json'

响应状态

状态	含义	响应结构
`200`	The policy	`PolicyView`
`401`	缺少或无效的 Bearer 令牌。	`ProblemDetails`
`404`	当前 Network 中不存在该访问授权。	`ProblemDetails`

200 响应

字段	类型	必有	说明
`action`	`string`	是	Effect (currently always `allow`).
`compile_error`	`string \| null`	否	Why the Grant is dropped. Absent while `compile_status` is `compiled`.
`compile_error_code`	`string \| null`	否	Stable token naming the same rejection as `compile_error`, for alerting that must not depend on wording. Absent while `compile_status` is `compiled`.
`compile_status`	`PolicyCompileStatusView`	是	Whether the grant can take effect. A rejected grant does not allow access even when enabled is true; inspect compile_error and compile_error_code.
`conditions`	`object`	是	Free-form conditions object.
`created_at`	`string`	是	Creation time (RFC 3339 UTC).
`created_by`	`string`	是	Label of the actor who created it.
`enabled`	`boolean`	是	Whether the policy is active.
`enforced_at`	`string`	是	Enforcement point (`node` \| `gateway`).
`id`	`string`	是	Policy ULID.
`name`	`string`	是	Display name.
`realm_id`	`string`	是	Owning realm ULID.
`resource`	`object`	是	What the policy grants access to (`{ type, … }`).
`subject`	`object`	是	Who the policy applies to (`{ type, … }`).
`version`	`integer`	是	Monotonic version, bumped on each update.

{
  "action": "allow",
  "compile_error": "example",
  "compile_error_code": "example",
  "compile_status": "compiled",
  "conditions": {},
  "created_at": "2026-09-09T10:00:00Z",
  "created_by": "example",
  "enabled": true,
  "enforced_at": "2026-09-09T10:00:00Z",
  "id": "01K4EXAMPLE0000000000000",
  "name": "示例资源",
  "realm_id": "01K4EXAMPLE0000000000000",
  "resource": {
    "type": "service",
    "service_id": "01K4SERVICE00000000000000"
  },
  "subject": {
    "type": "user",
    "user_id": "01K4USER000000000000000000"
  },
  "version": 1
}

错误响应均使用 Problem Details；调用方应判断 HTTP 状态和稳定的 code，不要解析 detail 文案。

修改访问授权

PATCH/api/v1/policies/{id}full

参数

名称	位置	类型	必填	说明
`id`	path	`string`	是	Policy ULID

请求体

字段	类型	必填	说明
`conditions`	`object`	否	New conditions object.
`enabled`	`boolean \| null`	否	Enable/disable the policy.
`enforced_at`	`string \| null`	否	Deprecated compatibility hint. NSD preserves an unchanged legacy policy shape or derives the enforcement point after a shape change.
`name`	`string \| null`	否	New display name.
`resource`	`object`	否	New resource object.
`subject`	`object`	否	New subject object.

request.json

{
  "conditions": {},
  "enabled": true,
  "enforced_at": "2026-09-09T10:00:00Z",
  "name": "示例资源",
  "resource": {
    "type": "service",
    "service_id": "01K4SERVICE00000000000000"
  },
  "subject": {
    "type": "user",
    "user_id": "01K4USER000000000000000000"
  }
}

请求示例

curl --silent --show-error --fail-with-body -X PATCH \
  "$NSD_BASE_URL/policies/${POLICY_ID}" \
  -H "Authorization: Bearer $NSD_TOKEN" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data @request.json

响应状态

状态	含义	响应结构
`200`	Updated policy with distribution summary	`PolicyMutationResponse`
`400`	主体无效，或主体/资源不属于当前 Network。	`ProblemDetails`
`401`	缺少或无效的 Bearer 令牌。	`ProblemDetails`
`404`	当前 Network 中不存在该访问授权。	`ProblemDetails`
`409`	OIDC 提供方与同一公网入口上的另一条访问授权冲突。	`ProblemDetails`

200 响应

字段	类型	必有	说明
`distribution`	`DistributionSummary`	是	Config-distribution summary for the realm.
`distribution.failed`	`integer`	是	Distribution failures (always 0 in the in-process path today).
`distribution.gateways`	`integer`	是	Gateways in the realm config was (re)distributed to.
`distribution.sites`	`integer`	是	Sites in the realm.
`policy`	`PolicyView`	是	The created/updated policy.
`policy.action`	`string`	是	Effect (currently always `allow`).
`policy.compile_error`	`string \| null`	否	Why the Grant is dropped. Absent while `compile_status` is `compiled`.
`policy.compile_error_code`	`string \| null`	否	Stable token naming the same rejection as `compile_error`, for alerting that must not depend on wording. Absent while `compile_status` is `compiled`.
`policy.compile_status`	`PolicyCompileStatusView`	是	Whether the grant can take effect. A rejected grant does not allow access even when enabled is true; inspect compile_error and compile_error_code.
`policy.conditions`	`object`	是	Free-form conditions object.
`policy.created_at`	`string`	是	Creation time (RFC 3339 UTC).
`policy.created_by`	`string`	是	Label of the actor who created it.
`policy.enabled`	`boolean`	是	Whether the policy is active.
`policy.enforced_at`	`string`	是	Enforcement point (`node` \| `gateway`).
`policy.id`	`string`	是	Policy ULID.
`policy.name`	`string`	是	Display name.
`policy.realm_id`	`string`	是	Owning realm ULID.
`policy.resource`	`object`	是	What the policy grants access to (`{ type, … }`).
`policy.subject`	`object`	是	Who the policy applies to (`{ type, … }`).
`policy.version`	`integer`	是	Monotonic version, bumped on each update.

{
  "distribution": {
    "failed": 1,
    "gateways": 1,
    "sites": 1
  },
  "policy": {
    "action": "allow",
    "compile_error": "example",
    "compile_error_code": "example",
    "compile_status": "compiled",
    "conditions": {},
    "created_at": "2026-09-09T10:00:00Z",
    "created_by": "example",
    "enabled": true,
    "enforced_at": "2026-09-09T10:00:00Z",
    "id": "01K4EXAMPLE0000000000000",
    "name": "示例资源",
    "realm_id": "01K4EXAMPLE0000000000000",
    "resource": {
      "type": "service",
      "service_id": "01K4SERVICE00000000000000"
    },
    "subject": {
      "type": "user",
      "user_id": "01K4USER000000000000000000"
    },
    "version": 1
  }
}

错误响应均使用 Problem Details；调用方应判断 HTTP 状态和稳定的 code，不要解析 detail 文案。

删除访问授权

DELETE/api/v1/policies/{id}full

参数

名称	位置	类型	必填	说明
`id`	path	`string`	是	Policy ULID

请求示例

curl --silent --show-error --fail-with-body -X DELETE \
  "$NSD_BASE_URL/policies/${POLICY_ID}" \
  -H "Authorization: Bearer $NSD_TOKEN" \
  -H 'Accept: application/json'

响应状态

状态	含义	响应结构
`204`	Policy deleted	`—`
`401`	缺少或无效的 Bearer 令牌。	`ProblemDetails`
`404`	当前 Network 中不存在该访问授权。	`ProblemDetails`

204 响应

成功，无响应体。

错误响应均使用 Problem Details；调用方应判断 HTTP 状态和稳定的 code，不要解析 detail 文案。

返回 API 参考总览。

#用户组与访问授权

#列出用户组

#参数

#请求示例

#响应状态

#200 响应

#创建用户组

#请求体

#请求示例

#响应状态

#201 响应

#读取用户组

#参数

#请求示例

#响应状态

#200 响应

#修改用户组

#参数

#请求体

#请求示例

#响应状态

#200 响应

#删除用户组

#参数

#请求示例

#响应状态

#204 响应

#列出组成员

#参数

#请求示例

#响应状态

#200 响应

#添加组成员

#参数

#请求体

#请求示例

#响应状态

#200 响应

#移除组成员

#参数

#请求示例

#响应状态

#204 响应

#列出访问授权

#参数

#请求示例

#响应状态

#200 响应

#创建访问授权

#请求体

#请求示例

#响应状态

#201 响应

#批量创建访问授权

#请求体

#请求示例

#响应状态

#201 响应

#读取访问授权

#参数

#请求示例

#响应状态

#200 响应

#修改访问授权

#参数

#请求体

#请求示例

#响应状态

#200 响应

#删除访问授权

#参数

#请求示例

#响应状态

#204 响应

用户组与访问授权

列出用户组

参数

请求示例

响应状态

200 响应

创建用户组

请求体

请求示例

响应状态

201 响应

读取用户组

参数

请求示例

响应状态

200 响应

修改用户组

参数

请求体

请求示例

响应状态

200 响应

删除用户组

参数

请求示例

响应状态

204 响应

列出组成员

参数

请求示例

响应状态

200 响应

添加组成员

参数

请求体

请求示例

响应状态

200 响应

移除组成员

参数

请求示例

响应状态

204 响应

列出访问授权

参数

请求示例

响应状态

200 响应

创建访问授权

请求体

请求示例

响应状态

201 响应

批量创建访问授权

请求体

请求示例

响应状态

201 响应

读取访问授权

参数

请求示例

响应状态

200 响应

修改访问授权

参数

请求体

请求示例

响应状态

200 响应

删除访问授权

参数

请求示例

响应状态

204 响应