高级 API 用法
mTLS 身份验证
双向 TLS(mTLS)可锁定 API 访问权限,只有出示有效客户端证书的计算机才能代表你的团队发起请求。它非常适合 API 流量经过自有网关、且需要通过密码学证明每个请求均来自授权系统的企业环境。
为什么使用 mTLS?
零信任安全 — 每个请求都必须通过证书证明身份,而不只是提供 API 密钥
适配网关 — 流量经由企业 API 网关、代理或服务网格路由时可自然使用
无需修改代码 — 启用后,只需在请求中附加客户端证书。所有现有 API 功能(模型、tool、流式传输)均保持不变
快速开始
1. 完成设置
联系 support@x.ai,并提供:
团队 ID(可在 xAI Console 中找到)
PEM 格式的 CA 证书
你的系统将使用的客户端证书中的通用名称(CN)
我们会配置你的团队,并在 mTLS 激活后进行确认。
2. 配置 mTLS endpoint
使用 https://mtls.api.x.ai,而不是 https://api.x.ai。这是唯一需要的改动。所有 API 路径(/v1/chat/completions、/v1/responses、/v1/embeddings 等)都以相同方式工作。
3. 附加客户端证书
每个请求都要包含客户端证书和私钥。示例如下:
curl https://mtls.api.x.ai/v1/chat/completions \\
--cert /path/to/client-cert.pem \\
--key /path/to/client-key.pem \\
-H "Content-Type: application/json" \\
-H "Authorization: Bearer $XAI_API_KEY" \\
-d '{
"messages": [
{
"role": "user",
"content": "Hello, world!"
}
],
"model": "grok-4.7",
"stream": false
}'身份验证工作原理
为团队启用 mTLS 后,每个请求都要经过两项检查:
证书验证 — 将根据你在设置时提供的 CA 证书验证客户端证书。未出示有效证书的请求会被拒绝,并返回
403 Forbidden。API 密钥验证 — 将照常检查 API 密钥。无效或缺失的密钥会被拒绝,并返回
401 Unauthorized。
两项检查均须通过,请求才能继续。其他行为(速率限制、计费、模型访问)与标准 endpoint 完全相同。
轮换证书
mTLS 支持在不中断服务的情况下轮换证书:
| 场景 | 操作 |
|---|---|
| 续期客户端证书(相同 CA、相同 CN) | 无需额外操作,直接开始使用新证书。 |
| 更新 CA(例如新的中间证书) | 联系 support@x.ai以上传更新后的 CA 证书包。 |
| 完全切换到其他 CA | 联系 support@x.ai以注册新的 CA 证书。 |
FAQ
必须使用 mTLS endpoint 吗?
如果团队将 mTLS 启用为必需,则必须使用。发送到 api.x.ai 的请求会因未出示客户端证书而被拒绝。如果你需要让部分 API 密钥在未使用 mTLS 的情况下工作,请联系支持团队讨论配置。
mTLS 可以使用区域 endpoint 吗?
mTLS 目前可用于全球 mtls.api.x.ai 端点。如需将 mTLS 与区域端点结合使用,请联系 support@x.ai。
需要哪种证书格式?
需要 PEM 格式的 X.509 证书。CA 证书(设置时提供)和客户端证书都必须采用 PEM 编码。
mTLS 是按 API 密钥还是按团队配置?
mTLS 在团队级别配置。团队中的所有 API 密钥共享相同的 mTLS 配置。
如何测试设置?
设置完成后,使用证书发起一个简单请求:
curl -v https://mtls.api.x.ai/v1/api-key \\
--cert /path/to/client-cert.pem \\
--key /path/to/client-key.pem \\
-H "Authorization: Bearer $XAI_API_KEY"响应成功即表示证书和 API 密钥均正常工作。如果看到 403 Forbidden,请检查证书是否由提供给 xAI 的 CA 签名。
最后更新:2026 年 9 月 11 日