> ## Documentation Index
> Fetch the complete documentation index at: https://docs.x.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticação

> Autentique o XDK Python com Bearer Token, OAuth 2.0 PKCE ou contexto de usuário OAuth 1.0a para chamar endpoints da X API e publicar em nome dos usuários.

A X API exige autenticação para todos os endpoints. O XDK oferece suporte a três métodos de autenticação:

1. Bearer Token (apenas de app)
2. OAuth 2.0 com PKCE
3. OAuth 1.0a (contexto de usuário)

* **Bearer Token**: Use isto para acesso somente-leitura em endpoints que suportam autenticação de app (por exemplo, pesquisar Posts, endpoints de streaming).
* **OAuth 2.0 PKCE**: Autenticação segura para acesso baseado em escopos, autorizado pelo usuário (por exemplo, obter métricas non\_public dos Posts do usuário autenticado).
* **OAuth 1.0a**: Autenticação legada para operações específicas do usuário (por exemplo, publicar em nome de um usuário, gerenciar listas).
  Obtenha credenciais no [Console do desenvolvedor da X](https://developer.x.com/en/portal/dashboard). Você precisará de uma conta de desenvolvedor aprovada e de um app com as permissões apropriadas (por exemplo, Read + Write).

## Criando um Client

Todos os fluxos de autenticação criam uma instância de `Client`:

```python theme={null}
from xdk import Client
```

### 1. Bearer Token (apenas de app)

Para operações somente-leitura sem contexto de usuário.
**Passos**:

1. No Console do desenvolvedor, gere um Bearer Token para seu app.
2. Passe-o para o `Client`.
   **Exemplo**:

```python theme={null}
client = Client(bearer_token="XXXXX")
```

**Uso**:

```python theme={null}
# 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 com PKCE (contexto de usuário)

Este exemplo mostra como usar OAuth 2.0 com Proof Key for Code Exchange (PKCE). Use isto para acesso específico do usuário (por exemplo, publicar em nome de um usuário, enviar mídia por um usuário etc.).
**Passos**:

1. No Console do desenvolvedor, registre seu app com um redirect URI (por exemplo, `http://localhost:8080/callback`).
2. Obtenha o Client ID (nenhum segredo é necessário para PKCE).
3. Inicie o fluxo, direcione o usuário para a URL de autorização e trate o callback.
   **Exemplo** (usando um servidor web para o callback):

```python title="Example" expandable lines wrap icon="python" theme={null}
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)
```

**Atualização de token** (automática no SDK para sessões de longa duração):

```python theme={null}
# 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)
```

### 3. OAuth 1.0a (contexto de usuário)

Para aplicações legadas ou casos de uso específicos que exigem autenticação OAuth 1.0a:
**Passos**:

1. No Console do desenvolvedor, obtenha sua API Key e API Secret.
2. Se você já tiver tokens de acesso, use-os diretamente. Caso contrário, conclua o fluxo OAuth 1.0a para obtê-los.
3. Crie uma instância OAuth1 e passe-a para o Client.
   **Exemplo** (com tokens de acesso existentes):

```python title="Example" lines wrap icon="python" theme={null}
from xdk import Client
from xdk.oauth1_auth import OAuth1
# Step 1: Create OAuth1 instance with credentials
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)
```

**Exemplo** (fluxo OAuth 1.0a completo):

```python title="Example" lines wrap icon="python" theme={null}
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)
# Step 4: User authorizes and you receive oauth_verifier
# In a real app, handle this via callback 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()
```

**Nota**:

* Nunca coloque segredos diretamente no código em produção; use variáveis de ambiente ou gerenciadores de segredos (por exemplo, `os.getenv("X_BEARER_TOKEN")`).
* Para PKCE, garanta HTTPS para os redirect URIs em produção.
* O SDK valida tokens e lança `xdk.AuthenticationError` em caso de falhas.
  Para exemplos de código detalhados usando o XDK Python, confira nosso [repositório de exemplos de código no GitHub](https://github.com/xdevplatform/samples/tree/main/python).