API 参考

一把密钥，权限恰好够用

API 密钥是具有细粒度作用域的 Bearer 令牌——只读、设备、ACL 或密钥。CI 流水线拿到的密钥只能注册节点，别无其他；Terraform 运行器拿到的则可以推送策略。两者都会按你设定的时间表过期。

✓CI 与自动化默认使用会过期的密钥
✓每次调用都会连同密钥名称记入审计日志
✓每把密钥每分钟 100 次请求，可按需提升

$ curl https://api.openvlan.com/v1/devices \

-H "Authorization: Bearer $OV_API_KEY"

# {"devices":[{"id":"node-1","name":

# "ci-runner","os":"linux","online":true ...}]}

策略写入先校验，后生效

任何内容都不会以半解析的状态进入你的 tailnet。PUT 一个格式错误或权限过宽的 ACL，API 会连同出错行一起拒绝——dry-run 端点让 CI 像测试代码一样测试策略变更。

# dry-run a policy change from CI

$ curl -X POST .../v1/acl/validate \

-d @policy-draft.json

# {"valid":false,"errors":[

# {"line":14,"msg":"group 'eng-production' undefined"}]}

# your tailnet: untouched, as designed

端点

方法	路径	说明
GET	/v1/devices	列出节点；可按用户、标签或在线状态筛选
GET	/v1/devices/{id}	节点详情：地址、路由、最后在线时间
DELETE	/v1/devices/{id}	移除节点并吊销其密钥
POST	/v1/devices/{id}/tags	应用或替换标签
GET	/v1/users	列出 tailnet 用户及其角色
GET	/v1/acl	获取当前 ACL 策略
PUT	/v1/acl	替换策略（应用前先校验）
POST	/v1/acl/validate	演练策略而不实际应用
GET	/v1/keys	列出身份验证密钥
POST	/v1/keys	创建带作用域、会过期的身份验证密钥
GET	/v1/routes	列出已通告的子网路由及审批状态
POST	/v1/routes/{id}/approve	批准待处理的子网路由
GET	/v1/logs/connections	分页的连接审计日志

常用示例

复制、粘贴、改改变量。

# create a 7-day CI key that auto-tags nodes

$ curl -X POST https://api.openvlan.com/v1/keys \

-H "Authorization: Bearer $OV_API_KEY" \

-d '{"reusable":true,"expiresIn":"168h",

"tags":["tag:ci"]}'

# list every node tagged for production

$ curl ".../v1/devices?tag=tag:prod&online=true" \

-H "Authorization: Bearer $OV_API_KEY"

# → 14 devices, all online, keys rotated < 30d

# approve a pending subnet route

$ curl -X POST .../v1/routes/route-77/approve \

-H "Authorization: Bearer $OV_API_KEY"

# → 10.0.4.0/22 now advertised to the tailnet

# pull yesterday's connection log for the SIEM

$ curl ".../v1/logs/connections?since=24h" \

-H "Authorization: Bearer $OV_API_KEY" \

> siem-inbound.ndjson

API 常见问题

如何在不停机的情况下轮换 API 密钥？

先创建新密钥，在密钥管理器中完成替换，再删除旧密钥。两把密钥同时有效，因此不会出现自动化被锁在门外的窗口期。大多数团队将轮换周期与 TLS 证书保持一致——每 90 天一次。

触发速率限制会怎样？

你会收到带 Retry-After 头的 429 响应，限额会在一分钟内重置。合法工作负载持续出现 429 通常意味着你在轮询——改用 since 参数读取连接日志，或者联系我们提升上限。

有 SDK 吗，还是只有原生 REST？

Go、Python 和 TypeScript 的开源客户端库封装了这套 API——端点相同，响应带类型。Terraform 用户则可以使用 provider，底层是同一套 API，以声明式资源呈现。

API 能与我的 SSO 身份协同工作吗？

API 密钥在设计上独立于用户身份——人员离职不应导致自动化中断。密钥在控制台访问层面继承 tailnet 级的 SSO 强制策略，SCIM 注销不影响密钥；限制由过期机制和作用域完成。

可以在沙盒 tailnet 上测试吗？

可以——免费版就是沙盒。建一个用完即弃的 tailnet，生成密钥，放手折腾。API 能力完全相同；区别只在席位数与高级功能。

一把密钥，权限恰好够用

策略写入先校验，后生效

端点

常用示例

API 常见问题

更习惯 Terraform？