身份验证

X API 要求所有端点均需身份验证。XDK 支持三种身份验证方式：

1. Bearer Token（仅限 App）
2. OAuth 2.0 with PKCE
3. OAuth 1.0a User Context

• Bearer Token：用于对支持 app-auth 的端点进行只读访问（例如搜索 Post、流式端点）。
• OAuth 2.0 PKCE：用于基于 scope 的、由用户授权的安全访问（例如获取已认证用户的 Post 非公开指标）。
• OAuth 1.0a：旧版身份验证，提供完整读/写访问，包括私信和媒体上传。

注意：我们建议开发者从 OAuth 1.0 迁移至 OAuth 2.0，用于用户授权访问。

从 X 开发者门户获取凭据。你需要一个已获批准的开发者账户，以及一个具备相应权限（例如读 + 写）的 App。

​

创建客户端

所有身份验证流程都会创建一个 Client 实例：

from xdk import Client

​

1. Bearer Token（仅限 App）

适用于无用户上下文的只读操作。

步骤：

1. 在开发者门户中为你的 App 生成 Bearer Token。
2. 将其传递给 Client。

示例：

client = Client(bearer_token="XXXXX")

使用方法：

response = client.posts.search_recent(query="python", max_results=10)
print(response.data[0]['text'])  # 访问第一条帖子

​

2. 使用 PKCE 的 OAuth 2.0（用户上下文）

本示例演示如何使用带有 Proof Key for Code Exchange（PKCE）的 OAuth 2.0。用于用户特定的访问（例如代表用户发布内容、为用户上传媒体等）。

步骤：

1. 在开发者门户中，使用重定向 URI（例如 http://localhost:8080/callback）注册你的 App。
2. 获取 Client ID（PKCE 无需 Client Secret）。
3. 启动流程，引导用户访问授权 URL 并处理回调。

示例（使用 Web 服务器处理回调）：

from xdk.auth import OAuth2PKCE
from urllib.parse import urlparse
import webbrowser

# 步骤 1：创建 PKCE 实例
auth = OAuth2PKCE(
    client_id="your_client_id",
    redirect_uri="http://localhost:8080/callback",
    scopes=["tweet.read", "users.read", "offline.access"]  # 根据需要调整范围
)

# 步骤 2：获取授权 URL
auth_url = auth.get_authorization_url()
print(f"访问此 URL 进行授权：{auth_url}")
webbrowser.open(auth_url)

# 步骤 3：处理回调（在实际应用中，使用 Flask 等 Web 框架）
# 假设 callback_url = "http://localhost:8080/callback?code=AUTH_CODE_HERE"
callback_url = input("在此粘贴完整的回调 URL：")
parsed = urlparse(callback_url)
code = parsed.query.split("=")[1]

# 步骤 4：用授权码交换令牌
tokens = auth.fetch_token(authorization_code=code)
access_token = tokens["access_token"]
refresh_token = tokens["refresh_token"]  # 存储以供更新使用

# 步骤 5：创建客户端
client = Client(oauth2_access_token=access_token)

令牌刷新（适用于长时会话，SDK 会自动处理）：

# 如果访问令牌过期，使用已存储的 refresh_token 进行刷新
tokens = auth.refresh_token(refresh_token=refresh_token)
client = Client(oauth2_access_token=tokens["access_token"])

​

3. OAuth 1.0a User Context

适用于需要 OAuth 1.0 支持的旧版端点。

步骤：

1. 通过开发者门户生成 Consumer Key/Secret 和 Access Token/Secret。
2. 在初始化客户端时将其传入。

示例：

from xdk.auth import OAuth1User

auth = OAuth1User(
    consumer_key="your_consumer_key",
    consumer_secret="your_consumer_secret",
    access_token="your_access_token",
    access_token_secret="your_access_token_secret"
)

client = Client(auth=auth)

注意：

• 切勿在生产环境中硬编码密钥；请使用环境变量或机密管理服务（例如 os.getenv("X_BEARER_TOKEN")）。
• 使用 PKCE 时，请在生产环境的重定向 URI 中确保使用 HTTPS。
• SDK 会验证令牌；验证失败时会抛出 xdk.AuthenticationError。