身份认证
每个需要认证的请求都携带一把 Bearer API 密钥。密钥标明你正在操作哪家酒店，以及你被允许使用哪些权限范围。这里没有用户名、密码或 OAuth 流程：一个集成对应一把密钥。
Veridien API 密钥形如：
vrdn_live_xxxxxxxxxxxxxxxxxxxx- 它以
vrdn_live_开头。 - 它只在创建时显示一次。Veridien 只保存密钥的 SHA-256 哈希值，密钥无法再次取回，只能吊销并重新签发。
- 它绑定一家酒店。酒店由密钥本身确定，因此任何接口都不会要你传酒店 id。
像对待密码一样对待密钥
一把密钥可以凭它的权限范围操作你线上的酒店数据。请把它放在服务端的密钥库或环境变量里，绝不要写进客户端代码或公开仓库。如果密钥泄露，请立即吊销并签发一把新的。
在仪表盘的设置 → API 密钥中创建密钥：
- 点击创建密钥，起一个说明用途的名称（例如
Sunrise Bay booking engine）。 - 勾选该集成所需的权限范围，按最小必要授予。
- 复制确认对话框中显示的密钥并妥善保存。它不会再次显示。
密钥随时可以在同一界面吊销。被吊销的密钥立即失效，之后使用它的请求会返回 401。
把密钥放进每个请求的 Authorization 头：
curl https://veridien.app/api/v1/me \
-H "Authorization: Bearer vrdn_live_xxxxxxxxxxxxxxxxxxxx"成功调用 /me 说明密钥可用，并会返回它对应的酒店与权限范围：
{
"property_id": "p_8f2a1c",
"property_slug": "sunrise-bay",
"scopes": ["availability:read", "reservations:write", "folio:write"],
"request_id": "req_a1b2c3d4e5"
}如果这个头缺失或格式不对，你会收到 401 missing_api_key；如果密钥未知、已停用或已过期，你会收到 401 invalid_api_key。
只有持有某个接口所需的权限范围，密钥才能调用该接口。缺少权限范围时调用会返回 403 insufficient_scope。权限范围采用 resource:action 的形式。
| 权限范围 | 授予的能力 |
|---|---|
availability:read | 读取房量与房价（/availability、/rates、/room-types、/services，以及已发布的优惠）。 |
rates:read | 读取房价管理类资源（GET /rate-plans/{id}/intervals、/inclusions、/promo-codes）。定价读取接口（/rates、/rate-plans）接受 availability:read。 |
rates:write | 创建、更新与删除房价方案和促销、季节区间、包含项与额度，以及促销码（/rate-plans、/intervals、/promo-codes）。 |
reservations:read | 列出与读取预订（/reservations、/reservations/{id}）。 |
reservations:write | 创建锁房、确认预订与取消（/holds、/holds/{id}/confirm、/reservations/{id}/cancel）。 |
guests:read | 读取客人档案，不含个人身份信息。 |
guests:read:pii | 额外返回客人的个人身份信息（邮箱、电话、地址、证件）。 |
guests:write | 注册、关联与更新客人（POST /guests、PATCH /guests/{id}）。 |
loyalty:read | 读取客人的积分余额、等级与流水。 |
loyalty:write | 兑换积分（/loyalty/redemptions）。 |
folio:read | 读取一条预订的账单。 |
folio:write | 向账单入账费用（/reservations/{id}/folio/charges）。 |
webhooks:manage | 预留给即将推出的 webhook 订阅管理。 |
最小权限
只授予集成真正需要的权限范围。一个只读的房量组件只需要 availability:read；一个完整的预订引擎通常需要 availability:read、guests:write、reservations:write 与 folio:write，如果还要展示积分，再加上 loyalty:*。
客人档案分为基础视图和个人信息视图。只持有 guests:read 时，你会收到标识符与非敏感字段（姓名、国籍、状态、本地居民核验标记）。若要额外收到 email、phone、address 与证件字段，密钥还必须持有 guests:read:pii。这样你就可以做一个面向公众的组件，读取客人状态而完全不暴露联系方式。
有两个元信息接口无需密钥、也无需权限范围：
GET /health：存活探测，返回{ "status": "ok" }。GET /openapi.json：整套 API 的 OpenAPI 3.1 描述。
其余接口都需要一把持有相应权限范围的有效密钥。