身份验证

签名请求（HMAC-SHA256）

每次调用都发送 X-API-Key、X-Timestamp、X-Nonce 和 X-Signature。签名覆盖请求方法、确切的请求目标（路径和查询）、时间戳、nonce 和请求体哈希，因此被重放或篡改的请求将无法通过验证。允许最多五分钟的时钟偏差；十分钟内重复使用 nonce 会被拒绝并返回 401 api_nonce_reused。

请基于实际发送的原始字节计算签名。JSON 只序列化一次，对这些字节计算哈希，并以完全相同的字节作为请求体发送——签名后重新序列化是导致 api_signature_invalid 最常见的原因。

const payload = JSON.stringify(body);
const ts = Math.floor(Date.now() / 1000);
const nonce = randomBytes(16).toString("hex");
const bodyHash = createHash("sha256").update(payload).digest("hex");
const canonical = ["POST", "/v1/flights/search", ts, nonce, bodyHash].join("\n");
const signature = createHmac("sha256", SECRET).update(canonical).digest("hex");

OAuth 2 客户端凭据

如果对每个请求签名不适合您的技术栈，可以在 POST /v1/oauth/token（grant_type=client_credentials，表单编码）用密钥 ID 和 Secret 换取短期 Bearer 令牌。令牌有效期为 30 分钟，携带您已获授予的权限范围；也可以通过 scope 参数只申请其中一部分。

每次调用时，以 Authorization: Bearer 方式发送令牌，并同时携带 X-API-Key。每个请求都会重新校验密钥 ID，因此吊销密钥会立即使其令牌失效。

curl -X POST "https://api.dubaitrip.com/v1/oauth/token" \
  -d grant_type=client_credentials -d client_id=$KEY_ID -d client_secret=$SECRET

密钥 ID、Secret 与轮换

沙箱密钥以 dt_sbx_ 开头，生产环境密钥以 dt_live_ 开头。每个密钥只属于一个环境和一个合作伙伴。Secret 只显示一次——在创建时、轮换时以及通过查看链接——在我们这边仅以哈希形式存储。

在开发者门户中进行轮换：系统会签发新的密钥 ID 和 Secret，旧密钥在您选择的宽限期内（最长七天）仍可使用，便于您无停机地完成切换。吊销则立即生效。

IP 白名单

您可以在开发者门户中，将每个环境限定为一组 IPv4/IPv6 地址或 CIDR 范围（可选）。来自其他地址的请求即使签名正确，也会被拒绝并返回 403 api_ip_not_allowed。列表留空则接受任何来源。