API 参考
对当前的 Tungsto API 进行身份验证
在与账户、账单和服务器端点集成之前，请了解支持的会话 Cookie 和 CSRF 契约。
开始之前
- 一个现有账户以及通过 HTTPS 访问正在运行的账户服务。
- 在请求之间保留会话cookie的客户端。
- 对于更改，需要与同一活动会话关联的CSRF令牌。
使用受支持的身份验证方法
受保护的API路由使用登录建立的账户会话。会话cookie名为__Host-tungsto-session，标记为Secure和HttpOnly。第二个cookie __Host-tungsto-csrf支持请求验证。账户更改需要与该会话匹配的x-csrf-token头，以及会话cookie。
SSH和API密钥屏幕用于创建、列出和撤销限定范围的密钥。发送 Authorization: Bearer 后跟一次性密钥。读取范围允许GET /api/v1/servers、服务器详情和 /api/v1/orders。服务器范围允许服务器、服务器详情和 /api/v1/network。账单范围允许GET /api/v1/ledger.。所有API密钥变更均被拒绝，即使同时存在浏览器会话。密码更改或账户恢复会撤销现有密钥。请勿围绕此本地预览构建无人值守的生产硬件或支付自动化。
建立并验证会话
上面的请求仅显示字段名称。请在您自己的客户端中安全地提供凭据；不要在共享示例或诊断输出中保存真实密码。来自浏览器的请求必须保持在同一站点上。命名其他来源的 Origin 头将被拒绝。
- 发送一个 JSON POST 请求到 /api/v1/auth/login，包含用户名和密码。将成功响应返回的 Set-Cookie 值保存在客户端的受保护 cookie 存储中。
- 将 JSON 响应中返回的 csrfToken 与该会话一起保留。不要将一次登录的令牌与另一次登录的 cookie 混用。
- 使用 cookies 调用 GET /api/v1/me 验证账户。其响应包含用户名、balanceUsd 和 csrfToken。
- 对于受保护的更改，请发送会话 Cookie、Content-Type: application/json 和 x-csrf-token。当端点需要时，请包含 Idempotency-Key。
- 客户端完成后，使用 POST /api/v1/auth/logout 结束会话。
POST /api/v1/auth/login HTTP/1.1
Content-Type: application/json
{"username":"your-username","password":"your-password"}处理会话过期和验证错误
成功的账户恢复会更改密码、撤销现有会话并发放新的恢复代码。使用早期 cookie 的客户端必须重新进行身份验证。服务还会使会话过期，因此之前成功的连接不是无限期的凭证。
| 响应 | 含义 | 下一步操作 |
|---|---|---|
| 401 authentication_required | 未找到有效的账户会话。 | 再次登录并保留新的cookie。 |
| 401 session_invalid | 会话和 CSRF cookie 无法一起验证。 | 开始新的登录，而不是重复使用混合的 cookie。 |
| 403 csrf_failed | 变更请求缺少匹配的验证令牌。 | 重新加载会话信息并使用其当前令牌。 |
| 403 origin_rejected | 提供的 Origin 与请求的来源不同。 | 从受支持的同一站点上下文运行请求。 |
| 429 rate_limited | 进行了过多的身份验证尝试。 | 请等待后再尝试；不要持续重试。 |
将集成保持在当前合同范围内
安全屏幕列出通过 GET /api/v1/sessions 的活动会话，并通过 DELETE /api/v1/sessions/:id. 撤销拥有的会话。密钥屏幕列出并撤销 API 密钥。没有 OAuth 流程。注册和恢复是交互式账户访问操作，不能替代服务账户机制。避免在多个工具或用户之间分发一个人的会话 cookie。
收到身份验证成功仅确认账户访问，并不确认每个外部操作都可用。加密货币结算需要连接的提供商；物理服务器操作需要操作员执行排队的请求。在将成功响应解释为已完成的现实操作之前，请阅读操作指南以了解特定端点的结果和重试行为。