Skip to main content
The X API requires authentication for all endpoints. The XDK supports two authentication methods:
  1. Bearer Token (app-only)
  2. OAuth 2.0 with PKCE
  • Bearer Token: Use this for read-only access for endpoints that support app-auth (e.g., searching Post’s, streaming endpoints).
  • OAuth 2.0 PKCE: Secure authentication for scope-based, user-authorized access (e.g. getting authenticated user’s Post non_public metrics) Obtain credentials from the X Developer Portal. You’ll need an approved developer account and an app with appropriate permissions (e.g., Read + Write).

​
Creating a Client

All authentication flows create a Client instance: 
from xdk import Client

​
1. Bearer Token (App-Only)

For read-only operations without user context. Steps:
  1. In the Developer Portal, generate a Bearer Token for your app.
  2. Pass it to the Client. Example:
client = Client(bearer_token="XXXXX")
Usage: 
# search_recent returns an Iterator, so iterate over it
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 with PKCE (User Context)

This example shows how to use OAuth 2.0 with Proof Key for Code Exchange (PKCE). Use this for user-specific access (e.g. posting on behalf of a user), uploading media for a user etc.). Steps:
  1. In the developer portal, register your app with a redirect URI (e.g., http://localhost:8080/callback).
  2. Get Client ID (no secret needed for PKCE).
  3. Initiate the flow, direct user to auth URL and handle callback. Example (using a web server for callback):
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)
# Step 3: Handle callback (in a real app, use a web framework like Flask)
# Assume 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)
Token Refresh (automatic in SDK for long-lived sessions): 
# If access token expires, refresh using stored refresh_token
# The refresh_token method uses the stored token from the OAuth2PKCEAuth instance
tokens = auth.refresh_token()
# Use the refreshed token
client = Client(bearer_token=tokens["access_token"])
# Or pass the full token dict: client = Client(token=tokens)
Note:
  • Never hardcode secrets in production; use environment variables or secret managers (e.g., os.getenv("X_BEARER_TOKEN")).
  • For PKCE, ensure HTTPS for redirect URIs in production.
  • The SDK validates tokens and raises xdk.AuthenticationError on failures.
For detailed code examples using the Python XDK, check out our code samples GitHub repo.