認証

X API では、すべてのエンドポイントで認証が必要です。XDK は次の 3 つの認証方法をサポートしています。

1. Bearer Token（アプリのみ）
2. OAuth 2.0 with PKCE
3. OAuth 1.0a（ユーザーコンテキスト）

• Bearer Token: app-auth（アプリ認証）をサポートするエンドポイントへの読み取り専用アクセスに使用します（例: ポスト検索、ストリーミングエンドポイント）。
• OAuth 2.0 with PKCE: スコープベースでユーザーが許可したアクセスを安全に行うために使用します（例: 認証済みユーザーのポストの非公開メトリクスを取得）。
• OAuth 1.0a: ユーザー固有の操作（例: ユーザーに代わってポストする、リストを管理する）向けのレガシーな認証方式です。

X 開発者コンソール から認証情報を取得してください。承認済みの開発者アカウントと、適切な権限（例: Read + Write）を持つ App が必要です。

​

Client の作成

すべての認証フローでは Client インスタンスが作成されます。

from xdk import Client

​

1. ベアラートークン (App-only)

ユーザーコンテキストを伴わない読み取り専用の操作に使用します。 手順:

1. 開発者コンソールで、対象の App 用のベアラートークンを生成します。
2. それを Client に渡します。 例:

client = Client(bearer_token="XXXXX")

使用方法:

# search_recent は Iterator を返すので、それを反復処理します
for page in client.posts.search_recent(query="python", max_results=10):
    if page.data and len(page.data) > 0:
        first_post = page.data[0]
        post_text = first_post.text if hasattr(first_post, 'text') else first_post.get('text', '')
        print(post_text)  # Access first Post
        break

​

2. OAuth 2.0 と PKCE を用いる場合（ユーザーコンテキスト）

この例では、Proof Key for Code Exchange（PKCE）を用いた OAuth 2.0 の使い方を示します。ユーザー単位のアクセス（例: ユーザーに代わってポストする）、ユーザー用のメディアアップロードなどに使用します。 手順:

1. 開発者コンソールで App を登録し、リダイレクト URI（例: http://localhost:8080/callback）を設定します。
2. Client ID を取得します（PKCE では secret は不要です）。
3. フローを開始し、ユーザーを認可 URL にリダイレクトしてコールバックを処理します。 例（コールバック用に Web サーバーを使用する場合）:

from xdk.oauth2_auth import OAuth2PKCEAuth
from urllib.parse import urlparse
import webbrowser
# Step 1: Create PKCE instance
auth = OAuth2PKCEAuth(
    client_id="YOUR_CLIENT_ID",
    redirect_uri="YOUR_CALLBACK_URL",
    scope="tweet.read users.read offline.access"
)
# Step 2: Get authorization URL
auth_url = auth.get_authorization_url()
print(f"Visit this URL to authorize: {auth_url}")
webbrowser.open(auth_url)
# ステップ3: コールバックを処理(実際のアプリではFlaskなどのWebフレームワークを使用)
# callback_url = "http://localhost:8080/callback?code=AUTH_CODE_HERE" と仮定
callback_url = input("Paste the full callback URL here: ")
# Step 4: Exchange code for tokens
tokens = auth.fetch_token(authorization_response=callback_url)
access_token = tokens["access_token"]
refresh_token = tokens["refresh_token"]  # Store for renewal
# Step 5: Create client
# Option 1: Use bearer_token (OAuth2 access tokens work as bearer tokens)
client = Client(bearer_token=access_token)
# Option 2: Pass the full token dict for automatic refresh support
# client = Client(token=tokens)

トークンのリフレッシュ（長時間のセッションでは SDK により自動的に実行されます）:

# アクセストークンの有効期限が切れた場合、保存されているrefresh_tokenを使用して更新
# refresh_tokenメソッドはOAuth2PKCEAuthインスタンスに保存されているトークンを使用
tokens = auth.refresh_token()
# 更新されたトークンを使用
client = Client(bearer_token=tokens["access_token"])
# または完全なトークン辞書を渡す: client = Client(token=tokens)

​

3. OAuth 1.0a (ユーザーコンテキスト)

レガシーなアプリケーションや、OAuth 1.0a 認証を必要とする特定のユースケース向けです:

手順:

1. 開発者コンソールで API キーと API シークレットを取得します。
2. すでにアクセストークンがある場合は、そのまま使用します。ない場合は、OAuth 1.0a フローを完了して取得します。
3. OAuth1 インスタンスを作成し、それを Client に渡します。 例（既存のアクセストークンを使用する場合）:

from xdk import Client
from xdk.oauth1_auth import OAuth1
# ステップ1: 認証情報を使用してOAuth1インスタンスを作成する
oauth1 = OAuth1(
    api_key="YOUR_API_KEY",
    api_secret="YOUR_API_SECRET",
    callback="http://localhost:8080/callback",
    access_token="YOUR_ACCESS_TOKEN",
    access_token_secret="YOUR_ACCESS_TOKEN_SECRET"
)
# ステップ2: OAuth1を使用してClientを作成する
client = Client(auth=oauth1)
# ステップ3: Clientを使用する
response = client.users.get_me()
me = response.data
print(me)

例（OAuth 1.0a フロー全体）：

from xdk import Client
from xdk.oauth1_auth import OAuth1
import webbrowser
# Step 1: Create OAuth1 instance
oauth1 = OAuth1(
    api_key="YOUR_API_KEY",
    api_secret="YOUR_API_SECRET",
    callback="http://localhost:8080/callback"
)
# Step 2: Get request token
request_token = oauth1.get_request_token()
# Step 3: Get authorization URL
auth_url = oauth1.get_authorization_url(login_with_x=False)
print(f"Visit this URL to authorize: {auth_url}")
webbrowser.open(auth_url)
# ステップ4: ユーザーが認証するとoauth_verifierを受け取ります
# 実際のアプリでは、コールバックURLを介してこれを処理します
oauth_verifier = input("Enter the OAuth verifier from the callback: ")
# Step 5: Exchange for access token
access_token = oauth1.get_access_token(oauth_verifier)
# Step 6: Create client
client = Client(auth=oauth1)
# Now you can use the client
response = client.users.get_me()

注意:

• 本番環境ではシークレットをハードコードせず、環境変数やシークレットマネージャー（例: os.getenv("X_BEARER_TOKEN")）を使用してください。
• PKCE を使用する場合、本番環境のリダイレクト URI には必ず HTTPS を使用してください。
• SDK はトークンを検証し、失敗した場合は xdk.AuthenticationError を送出します。 Python 用 XDK を用いたコード例の詳細については、コードサンプルの GitHub リポジトリを参照してください。