高级 API 使用

mTLS 认证

双向 TLS (mTLS) 可让您锁定 API 访问权限，只有提供有效客户端证书的机器才能代表您的团队发出请求。这非常适合企业环境，其中 API 流量通过您自己的网关传输，并且您需要密码学证明每个请求都来自授权系统。

TIP

mTLS 是企业级功能。请联系 support@x.ai 为您的团队启用它。

为什么使用 mTLS？

• 零信任安全 — 每个请求都必须用证书证明其身份，而不仅仅是 API 密钥
• 网关友好 — 当您的流量通过企业 API 网关、代理或服务网格路由时，可自然工作
• 无需代码更改 — 启用后，您只需要将客户端证书附加到请求中。所有现有 API 功能（模型、工具、流式传输）都完全相同

快速开始

1. 准备工作

联系 support@x.ai 并提供：

• 您的团队 ID（在 xAI 控制台 中找到）
• PEM 格式的 CA 证书
• 您的系统将使用的客户端证书中的通用名称 (CN)

我们将配置您的团队并在 mTLS 激活时通知您。

2. 指向 mTLS 端点

使用 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.5",
    "stream": false
  }'

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.5",
    messages=[
        {"role": "user", "content": "Hello, world!"}
    ]
)
print(completion.choices[0].message.content)

import OpenAI from 'openai';
import https from 'https';
import fs from 'fs';

const client = new OpenAI({
    apiKey: process.env.XAI_API_KEY,
    baseURL: 'https://mtls.api.x.ai/v1',
    httpAgent: new https.Agent({
        cert: fs.readFileSync('/path/to/client-cert.pem'),
        key: fs.readFileSync('/path/to/client-key.pem'),
    }),
});

const completion = await client.chat.completions.create({
    model: 'grok-4.5',
    messages: [
        { role: 'user', content: 'Hello, world!' }
    ],
});

console.log(completion.choices[0].message.content);

NOTE

您仍然需要在每个请求上使用有效的 API 密钥。mTLS 是额外的安全层，而不是 API 密钥认证的替代品。

认证工作原理

当为您的团队启用 mTLS 时，每个请求都会经过两项检查：

1. 证书验证 — 根据您在设置期间提供的 CA 证书验证您的客户端证书。没有有效证书的请求将被拒绝并返回 403 Forbidden。
2. API 密钥验证 — 像往常一样检查您的 API 密钥。无效或缺失的密钥将被拒绝并返回 401 Unauthorized。

两项检查都必须通过请求才能继续。所有其他行为（速率限制、计费、模型访问）与标准端点相同。

旋转证书

mTLS 的设计使您可以在不停机的情况下旋转证书：

场景	操作
续订客户端证书（相同的 CA，相同的 CN）	无需操作。只需开始使用新证书即可。
更新您的 CA（例如，新的中间证书）	联系 support@x.ai 上传更新的 CA 包。
完全切换到不同的 CA	联系 support@x.ai 注册新的 CA 证书。

常见问题

我必须使用 mTLS 端点吗？

如果 mTLS 被设置为必需，则必须使用。对 api.x.ai 的请求将被拒绝，因为没有提供客户端证书。如果您需要某些 API 密钥在没有 mTLS 的情况下工作，请联系支持讨论您的配置。

我可以将 mTLS 与区域端点一起使用吗？

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 签名。