Autenticación

La X API requiere autenticación para todos los endpoints. El XDK admite tres métodos de autenticación:

1. Bearer Token (solo App)
2. OAuth 2.0 con PKCE
3. OAuth 1.0a (Contexto de usuario)

• Bearer Token: Utiliza este método para acceso de solo lectura a endpoints que admiten autenticación de App (por ejemplo, búsqueda de Publicaciones, endpoints de streaming).
• OAuth 2.0 PKCE: Autenticación segura para acceso basado en scopes y autorizado por el usuario (por ejemplo, obtener las métricas non_public de las Publicaciones del usuario autenticado).
• OAuth 1.0a: Autenticación heredada para operaciones específicas de usuario (por ejemplo, publicar en nombre de un usuario, administrar Listas).

Obtén las credenciales en la Consola de desarrollador de X. Necesitarás una cuenta de desarrollador aprobada y una App con los permisos adecuados (por ejemplo, Lectura + Escritura).

​

Crear un Client

Todos los flujos de autenticación crean una instancia de Client:

from xdk import Client

​

1. Bearer Token (solo App)

Para operaciones de solo lectura sin contexto de usuario. Pasos:

1. En la Consola de desarrollador, genera un Bearer Token para tu App.
2. Pásalo al Client. Ejemplo:

client = Client(bearer_token="XXXXX")

Uso:

# search_recent devuelve un Iterator, así que itera sobre él
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 con PKCE (contexto de usuario)

Este ejemplo muestra cómo usar OAuth 2.0 con Proof Key for Code Exchange (PKCE). Utiliza este flujo para acceso específico de usuario (por ejemplo, publicar en nombre de un usuario o subir contenido multimedia para un usuario). Pasos:

1. En la Consola de desarrollador, registra tu App con un URI de redirección (por ejemplo, http://localhost:8080/callback).
2. Obtén el Client ID (no se necesita secreto para PKCE).
3. Inicia el flujo, dirige al usuario a la URL de autenticación y gestiona el callback. Ejemplo (usando un servidor web para el 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
# Opción 1: Usar bearer_token (los tokens de acceso OAuth2 funcionan como Bearer Tokens)
client = Client(bearer_token=access_token)
# Option 2: Pass the full token dict for automatic refresh support
# client = Client(token=tokens)

Renovación del token (automática en el SDK para sesiones prolongadas):

# Si el token de acceso expira, actualízalo usando el refresh_token almacenado
# El método refresh_token usa el token almacenado de la instancia OAuth2PKCEAuth
tokens = auth.refresh_token()
# Usa el token actualizado
client = Client(bearer_token=tokens["access_token"])
# O pasa el diccionario completo de tokens: client = Client(token=tokens)

​

3. OAuth 1.0a (Contexto de usuario)

Para aplicaciones heredadas o casos de uso específicos que requieren autenticación con OAuth 1.0a: Pasos:

1. En la Consola de desarrollador, obtén tu API Key y API Secret.
2. Si ya tienes tokens de acceso, úsalos directamente. De lo contrario, completa el flujo de OAuth 1.0a para obtenerlos.
3. Crea una instancia de OAuth1 y pásala al Client. Ejemplo (con tokens de acceso existentes):

from xdk import Client
from xdk.oauth1_auth import OAuth1
# Paso 1: Crear instancia de OAuth1 con credenciales
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"
)
# Step 2: Create client with OAuth1
client = Client(auth=oauth1)
# Step 3: Use the client
response = client.users.get_me()
me = response.data
print(me)

Ejemplo (flujo completo de OAuth 1.0a):

from xdk import Client
from xdk.oauth1_auth import OAuth1
import webbrowser
# Paso 1: Crear instancia de OAuth1
oauth1 = OAuth1(
    api_key="YOUR_API_KEY",
    api_secret="YOUR_API_SECRET",
    callback="http://localhost:8080/callback"
)
# Paso 2: Obtener el token de solicitud
request_token = oauth1.get_request_token()
# Paso 3: Obtener la URL de autorización
auth_url = oauth1.get_authorization_url(login_with_x=False)
print(f"Visita esta URL para autorizar: {auth_url}")
webbrowser.open(auth_url)
# Paso 4: El usuario autoriza y recibes el oauth_verifier
# En una aplicación real, maneja esto a través de la URL de callback
oauth_verifier = input("Ingresa el verificador de OAuth del callback: ")
# Paso 5: Intercambiar por el token de acceso
access_token = oauth1.get_access_token(oauth_verifier)
# Paso 6: Crear el Client
client = Client(auth=oauth1)
# Ahora puedes usar el Client
response = client.users.get_me()

Nota:

• Nunca codifiques secretos directamente en producción; usa variables de entorno o gestores de secretos (por ejemplo, os.getenv("X_BEARER_TOKEN")).
• Para PKCE, asegúrate de que las URI de redirección usen HTTPS en producción.
• El SDK valida los tokens y lanza xdk.AuthenticationError en caso de fallos. Para ver ejemplos de código detallados que usan el XDK de Python, consulta nuestro repositorio de ejemplos de código en GitHub.