高级 API 用法

mTLS 身份验证

查看 Markdown

双向 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 后,每个请求都要经过两项检查:

  1. 证书验证 — 将根据你在设置时提供的 CA 证书验证客户端证书。未出示有效证书的请求会被拒绝,并返回 403 Forbidden

  2. 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 配置。

如何测试设置?

设置完成后,使用证书发起一个简单请求:

Bash

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 日