NetSeed Docs

身份与用户

验证令牌上下文，并读取当前 Network 中的用户。 本页完整列出 3 个受支持操作的请求与响应契约。

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

读取当前身份

GET/api/v1/meread-only / full

请求示例

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

响应状态

状态含义响应结构
200返回当前用户及所在 Network/Organization 上下文。MeResponse
401缺少或无效的 Bearer 令牌。ProblemDetails

200 响应

字段类型必有说明
created_atstring是Row creation timestamp (RFC 3339 UTC).
disabledboolean是When true, the user cannot authenticate.
emailstring是User::email.
idstring是User::id, ULID as string.
last_login_atstring | null否Last successful login, if any (RFC 3339 UTC).
mfa_enabledboolean是MFA opt-in.
namestring是User::name.
oidc_substring | null否OIDC subject; None for local-password users.
realm_idstring是User::realm_id, ULID as string.
roleUserRole是User::role.
realm_slugstring | null是当前 Network 的可读标识；无法读取时为 null。
realm_namestring | null是当前 Network 的显示名称；无法读取时为 null。
realm_created_atstring | null是当前 Network 的创建时间；无法读取时为 null。
org_planstring | null是当前 Organization 的套餐标识；无法读取时为 null。
{
  "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": "示例资源",
  "oidc_sub": "example",
  "realm_id": "01K4EXAMPLE0000000000000",
  "role": "admin",
  "realm_slug": "example",
  "realm_name": "example",
  "realm_created_at": "2026-09-09T10:00:00Z",
  "org_plan": "example"
}

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

列出用户

GET/api/v1/usersread-only / full

参数

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

请求示例

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

响应状态

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

200 响应

字段类型必有说明
itemsarray<AdminUserView>是Users in this page.
items[].created_atstring是Creation timestamp (RFC 3339 UTC).
items[].disabledboolean是Whether the user is disabled.
items[].emailstring是Email address.
items[].idstring是User ULID.
items[].last_login_atstring | null否Last login timestamp (RFC 3339 UTC), or null.
items[].mfa_enabledboolean是Whether MFA is enabled.
items[].namestring是Display name.
items[].realm_idstring是Owning realm ULID.
items[].rolestring是Role (admin or member).
next_cursorstring | null否Cursor for the next page, or null when there is no next page.
{
  "items": [
    {
      "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"
    }
  ],
  "next_cursor": "example"
}

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

读取用户

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

参数

名称位置类型必填说明
idpathstring是User ULID

请求示例

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

响应状态

状态含义响应结构
200当前 Network 中的用户。AdminUserView
401缺少或无效的 Bearer 令牌。ProblemDetails
404当前 Network 中不存在该用户。ProblemDetails

200 响应

字段类型必有说明
created_atstring是Creation timestamp (RFC 3339 UTC).
disabledboolean是Whether the user is disabled.
emailstring是Email address.
idstring是User ULID.
last_login_atstring | null否Last login timestamp (RFC 3339 UTC), or null.
mfa_enabledboolean是Whether MFA is enabled.
namestring是Display name.
realm_idstring是Owning realm ULID.
rolestring是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 文案。

返回 API 参考总览。