Skip to main content
The Client class is the primary entry point for the XDK. It handles authentication, session management, OAuth2 PKCE flows, and provides access to all API functionality through sub-clients.

​
Constructor

Client(
    base_url: str = "https://api.x.com",
    bearer_token: str = None,
    access_token: str = None,
    client_id: str = None,
    client_secret: str = None,
    redirect_uri: str = None,
    token: Dict[str, Any] = None,
    scope: Union[str, List[str]] = None,
    authorization_base_url: str = "https://x.com/i",
    auth: OAuth1 = None,
)

​
Parameters

​
base_url
str
default:"https://api.x.com"
The base URL for the X API.
​
bearer_token
str
default:"None"
The bearer token for app-only authentication. Use this for application-level access without user context.
​
access_token
str
default:"None"
The OAuth2 access token for user context. Can be used directly as a bearer token for authenticated requests.
​
client_id
str
default:"None"
The client ID for OAuth2 PKCE flow. Required when using OAuth2 authorization.
​
client_secret
str
default:"None"
The client secret for OAuth2. Optional for PKCE flow.
​
redirect_uri
str
default:"None"
The redirect URI for OAuth2 authorization callback.
​
token
Dict[str, Any]
default:"None"
An existing OAuth2 token dictionary. If provided, the access_token will be extracted automatically.
​
scope
Union[str, List[str]]
default:"None"
OAuth2 authorization scopes. Can be a space-separated string or list of scope strings.
​
authorization_base_url
str
default:"https://x.com/i"
The base URL for OAuth2 authorization endpoints.
​
auth
OAuth1
default:"None"
OAuth1 instance for OAuth1.0a authentication.

​
Example

from xdk import Client

# App-only authentication with bearer token
client = Client(bearer_token="YOUR_BEARER_TOKEN")

# User context with access token
client = Client(access_token="YOUR_ACCESS_TOKEN")

​
Properties

​
oauth2_session

@property
def oauth2_session(self)
Returns the OAuth2 session object if OAuth2 authentication is configured. Returns: OAuth2Session or None

​
token

@property
def token(self)
Returns the current OAuth2 token dictionary if available. Returns: Dict[str, Any] or None Token structure: 
{
    "access_token": "...",
    "refresh_token": "...",
    "expires_at": 1234567890,
    "scope": ["tweet.read", "tweet.write"],
    "token_type": "bearer"
}

​
access_token

@property
def access_token(self)
Returns the current access token string. Checks for directly set access token first, then falls back to OAuth2 token. Returns: str or None 
# Setter available
client.access_token = "NEW_ACCESS_TOKEN"

​
OAuth Methods

​
get_authorization_url

def get_authorization_url(self, state=None) -> str
Generates the authorization URL for OAuth2 PKCE flow. Requires client_id to be configured.
​
state
str
default:"None"
Optional state parameter for CSRF protection.
Returns: str - The authorization URL to redirect users to Raises: ValueError if OAuth2 credentials not configured

​
Example

client = Client(
    client_id="YOUR_CLIENT_ID",
    redirect_uri="http://localhost:3000/callback",
    scope=["tweet.read", "users.read"]
)

# Generate authorization URL
auth_url = client.get_authorization_url(state="random_state_string")
print(f"Redirect user to: {auth_url}")

​
exchange_code

def exchange_code(self, code, code_verifier=None) -> Dict[str, Any]
Exchanges an authorization code for access tokens. Automatically updates the client’s access_token property.
​
code
str
required
The authorization code received from the callback.
​
code_verifier
str
default:"None"
The PKCE code verifier. If not provided, uses the stored verifier from get_authorization_url().
Returns: Dict[str, Any] - Token dictionary containing access_token, refresh_token, etc. Raises: ValueError if OAuth2 credentials not configured

​
Example

# After user authorizes and returns with code
code = request.args.get('code')
token = client.exchange_code(code)

print(f"Access token: {token['access_token']}")
print(f"Refresh token: {token['refresh_token']}")

# Client's access_token is now automatically set
print(f"Client access token: {client.access_token}")

​
fetch_token

def fetch_token(self, authorization_response) -> Dict[str, Any]
Fetches token using the full authorization response URL. This is a legacy method that parses the code from the callback URL.
​
authorization_response
str
required
The full callback URL received after authorization (including query parameters).
Returns: Dict[str, Any] - Token dictionary Raises: ValueError if OAuth2 credentials not configured

​
Example

# After OAuth callback
callback_url = "http://localhost:3000/callback?code=AUTH_CODE&state=STATE"
token = client.fetch_token(callback_url)

​
refresh_token

def refresh_token(self) -> Dict[str, Any]
Refreshes the OAuth2 access token using the refresh token. Automatically updates the client’s access_token property. Returns: Dict[str, Any] - New token dictionary Raises: ValueError if OAuth2 credentials not configured

​
Example

# Check if token is expired and refresh if needed
if client.is_token_expired():
    new_token = client.refresh_token()
    print(f"New access token: {new_token['access_token']}")

​
is_token_expired

def is_token_expired(self) -> bool
Checks whether the current OAuth2 token is expired. Returns: bool - True if expired or no token available, False otherwise

​
Example

if client.is_token_expired():
    print("Token expired, refreshing...")
    client.refresh_token()
else:
    print("Token still valid")

​
Sub-Clients

The Client provides access to all X API functionality through specialized sub-clients:

​
Posts

client.posts
Access to Posts API for creating, reading, and managing posts (tweets). See Posts API for details.

​
Users

client.users
Access to Users API for user profiles, follows, blocks, and mutes. See Users API for details.

​
Direct Messages

client.direct_messages
Access to Direct Messages API for sending and managing DMs.

​
Lists

client.lists
Access to Lists API for creating and managing Twitter lists.

​
Spaces

client.spaces
Access to Spaces API for audio spaces functionality.

​
Media

client.media
Access to Media API for uploading images, videos, and GIFs. 
client.trends
Access to Trends API for trending topics and hashtags.

​
Communities

client.communities
Access to Communities API for community management.

​
Community Notes

client.community_notes
Access to Community Notes API (formerly Birdwatch).

​
Connections

client.connections
Access to Connections API for managing user connections.

​
Compliance

client.compliance
Access to Compliance API for compliance jobs and batch operations.

​
Webhooks

client.webhooks
Access to Webhooks API for webhook subscriptions.

​
Account Activity

client.account_activity
Access to Account Activity API for real-time account events.

​
Stream

client.stream
Access to Streaming API for filtered and sampled streams.

​
Chat

client.chat
Access to Chat API functionality.

​
Usage

client.usage
Access to Usage API for rate limit and quota information.

​
General

client.general
Access to General API endpoints.

​
News

client.news
Access to News API endpoints.

​
Activity

client.activity
Access to Activity API endpoints.

​
Complete Example

from xdk import Client

# Initialize client with OAuth2
client = Client(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
    redirect_uri="http://localhost:3000/callback",
    scope=["tweet.read", "tweet.write", "users.read", "follows.read"]
)

# Step 1: Get authorization URL
auth_url = client.get_authorization_url(state="secure_random_state")
print(f"Visit: {auth_url}")

# Step 2: After user authorizes, exchange code
code = input("Enter the code from callback: ")
token = client.exchange_code(code)
print(f"Authenticated! Access token: {token['access_token'][:20]}...")

# Step 3: Use the client to make API calls
me = client.users.get_me()
print(f"Logged in as: {me['data']['username']}")

# Create a post
post = client.posts.create_post(text="Hello from XDK!")
print(f"Posted: {post['data']['id']}")

# Step 4: Refresh token when expired
if client.is_token_expired():
    client.refresh_token()
    print("Token refreshed!")

Build docs developers (and LLMs) love

Get started for freeTalk to us