#API 访问

NSD 管理 API 用于把资产查询、授权配置和审计接入脚本、CI 或业务后端。进入 开发者 → API 访问，为每个集成单独创建一个个人访问令牌；令牌以 nsda_ 开头，明文只显示一次。

#不要混用两类凭据

两类凭据在认证链路和授权对象上相互隔离。工作负载 API Key 即使泄露，也不能被当作管理令牌使用。

#创建最小权限令牌

1. 打开 开发者 → API 访问，点击 创建令牌。
2. 用集成用途命名，例如 inventory-readonly 或 billing-sync，不要用“test1”一类无法追踪的名称。
3. 选择最小作用域和最短可用有效期。默认建议 只读 + 90 天。
4. 创建后立即把明文保存到密钥管理系统。关闭弹窗后无法再次读取，只能创建新令牌并吊销旧令牌。

创建后列表只显示名称、前缀、作用域、状态、最近使用与过期时间。令牌前缀用于识别，不可用于还原秘密；完整令牌不会再次返回。

用户被停用、令牌过期或令牌被吊销后，认证立即失败。创建者角色被收窄时，令牌也不会保留更高权限。

#发起第一个请求

页面的“接入 API”区域按行提供 API Base URL、鉴权请求头、验证当前身份命令，每行右侧都可复制。验证命令完整显示，换行符可直接粘贴到终端；它使用环境变量，不包含你的令牌明文。

Base URL 是当前 NSD 地址加 /api/v1。不要把令牌直接写进命令历史、源码或流水线日志；使用环境变量或密钥注入。

export NSD_BASE_URL='https://nsd.example.com/api/v1'
export NSD_TOKEN='nsda_...'

curl -fsS "$NSD_BASE_URL/me" \
  -H "Authorization: Bearer $NSD_TOKEN" \
  -H 'Accept: application/json'

返回当前用户和 Network 信息表示鉴权成功。随后先调用一个只读资源确认可见范围，再用预期会被拒绝的操作验证最小权限边界。

#最小集成模板

1. 启动时从密钥管理系统读取 NSD_TOKEN，不把值写入日志。
2. 设置连接、读取和总体超时，并限制最大响应体。
3. 对 429 和可恢复的 5xx 使用带抖动的指数退避；不要重试 400、401 或权限明确不足的 403。
4. 分页读取时保存服务端返回的 opaque cursor，不自行解析或拼接。
5. 变更请求失败后重新读取当前资源，不盲目覆盖冲突状态。

#正确处理响应

错误响应使用 application/problem+json。自动化应依据 HTTP 状态和稳定错误代码分支，不要解析面向用户的提示文案。

#轮换与吊销

1. 在旧令牌仍有效时创建相同最小作用域的新令牌。
2. 更新密钥管理系统并让调用方重新加载。
3. 用新令牌验证成功路径与拒绝路径。
4. 在 NSD 列表中吊销旧令牌，确认旧令牌返回 401。

每个集成使用独立令牌后，单独轮换或吊销不会影响其他系统。发现泄露时先吊销，再调查活动日志；不要等待原有效期结束。

下一步：查看受支持的 API 参考 · 配置 Webhook