高级 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. 附加客户端证书
每个请求都要包含客户端证书和私钥。示例如下：
import os
import httpx
from openai import OpenAI
# Attach your client certificate to the HTTP transport
http_client = httpx.Client(
cert=("/path/to/client-cert.pem", "/path/to/client-key.pem")
)
client = OpenAI(
api_key=os.getenv("XAI_API_KEY"),
base_url="https://mtls.api.x.ai/v1",
http_client=http_client,
)
completion = client.chat.completions.create(
model="grok-4.7",
messages=[
{"role": "user", "content": "Hello, world!"}
]
)
print(completion.choices[0].message.content)身份验证工作原理
为团队启用 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，请检查证书是否由提供给 SpaceXSI 的 CA 签名。
最后更新：2026 年 10 月 31 日