Autenticação: chaves de API e OAuth

Por que a autenticação é importante para os agentes

import requests

# Without auth — will get 401
response = requests.get('https://api.openai.com/v1/models')
print(response.status_code)  # 401 Unauthorized

# With API key in header — works
headers = {'Authorization': 'Bearer sk-proj-abc123'}
response = requests.get(
    'https://api.openai.com/v1/models',
    headers=headers
)
print(response.status_code)  # 200

Chave de API no cabeçalho de autorização

import requests
import os

api_key = os.environ['OPENAI_API_KEY']

response = requests.post(
    'https://api.openai.com/v1/chat/completions',
    headers={
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json'
    },
    json={
        'model': 'gpt-4o-mini',
        'messages': [{'role': 'user', 'content': 'Hello!'}]
    }
)
print(response.json()['choices'][0]['message']['content'])

Chave de API em cabeçalho personalizado (X-API-Key)

import requests
import os

api_key = os.environ['SERVICE_API_KEY']

response = requests.get(
    'https://api.someservice.com/v1/data',
    headers={
        'X-API-Key': api_key,
        'Accept': 'application/json'
    }
)

if response.status_code == 200:
    data = response.json()
    print('Got data:', data)
elif response.status_code == 401:
    print('Invalid API key — check X-API-Key header')

Armazenamento de credenciais em variáveis de ambiente

import os

os.environ['OPENAI_API_KEY'] = 'sk-proj-abc123xyz789'  # simulate a set env var

api_key = os.environ.get('OPENAI_API_KEY')
if not api_key:
    raise EnvironmentError(
        'OPENAI_API_KEY environment variable not set. '
        'Run: export OPENAI_API_KEY=your-key-here'
    )

print('API key loaded from environment (never hard-code it in source)')

Desenvolvimento local com python-dotenv

# .env file (never commit this!)
# OPENAI_API_KEY=sk-proj-abc123
# ANTHROPIC_API_KEY=sk-ant-xyz456
# GITHUB_TOKEN=ghp_abc789

# In your Python code:
from dotenv import load_dotenv
import os

load_dotenv()  # loads .env into os.environ

openai_key = os.environ['OPENAI_API_KEY']
anthropic_key = os.environ['ANTHROPIC_API_KEY']
github_token = os.environ['GITHUB_TOKEN']

print('Keys loaded successfully')

O que é OAuth 2.0?

# OAuth flow overview:
#
# 1. Agent redirects user to:
#    https://auth.provider.com/oauth/authorize
#      ?client_id=YOUR_CLIENT_ID
#      &redirect_uri=http://localhost:8080/callback
#      &scope=read:repo%20write:issues
#      &response_type=code
#
# 2. User logs in and grants permission
# 3. Provider redirects to your callback with ?code=AUTH_CODE
# 4. Agent exchanges code for access_token
# 5. Agent uses access_token for API calls

print('OAuth flow: authorize -> code -> token -> API calls')

Fluxo de credenciais do cliente do OAuth2

import requests
import os

client_id = os.environ['OAUTH_CLIENT_ID']
client_secret = os.environ['OAUTH_CLIENT_SECRET']
token_url = 'https://auth.example.com/oauth/token'

# Request an access token
response = requests.post(token_url, data={
    'grant_type': 'client_credentials',
    'client_id': client_id,
    'client_secret': client_secret,
    'scope': 'read:data write:tasks'
})

token_data = response.json()
access_token = token_data['access_token']
expires_in = token_data['expires_in']  # seconds
print(f'Token valid for {expires_in}s')

Usando tokens OAuth em chamadas de API

import requests
import os
import time

class OAuthClient:
    def __init__(self, client_id, client_secret, token_url):
        self.client_id = client_id
        self.client_secret = client_secret
        self.token_url = token_url
        self.access_token = None
        self.token_expiry = 0

    def get_token(self):
        if time.time() < self.token_expiry - 60:  # 60s buffer
            return self.access_token
        r = requests.post(self.token_url, data={
            'grant_type': 'client_credentials',
            'client_id': self.client_id,
            'client_secret': self.client_secret
        })
        data = r.json()
        self.access_token = data['access_token']
        self.token_expiry = time.time() + data['expires_in']
        return self.access_token

    def get(self, url):
        token = self.get_token()
        return requests.get(url, headers={'Authorization': f'Bearer {token}'})

OAuth 2.0 com a biblioteca google-auth

from google.oauth2 import service_account
from google.auth.transport.requests import AuthorizedSession

# Load service account credentials from JSON file
credentials = service_account.Credentials.from_service_account_file(
    'service-account.json',
    scopes=[
        'https://www.googleapis.com/auth/gmail.readonly',
        'https://www.googleapis.com/auth/calendar.events'
    ]
)

# AuthorizedSession auto-refreshes tokens
session = AuthorizedSession(credentials)

response = session.get(
    'https://www.googleapis.com/gmail/v1/users/me/messages'
)
print(response.json())

Práticas recomendadas de segurança para chaves de API

import os

os.environ['OPENAI_API_KEY'] = 'sk-proj-abc123xyz789'

def get_key(env_var):
    key = os.environ.get(env_var)
    if not key:
        raise EnvironmentError(f'Missing required env var: {env_var}')
    return key

def mask_key(key):
    if len(key) < 8:
        return '***'
    return key[:4] + '...' + key[-4:]

api_key = get_key('OPENAI_API_KEY')
print(f'Using key: {mask_key(api_key)}')

Lidando com 401 Não autorizado no seu agente

import requests
import os

def call_api_with_auth_check(url, api_key):
    response = requests.get(
        url,
        headers={'Authorization': f'Bearer {api_key}'}
    )
    if response.status_code == 401:
        error = response.json().get('error', {})
        code = error.get('code', 'unknown')
        if code == 'token_expired':
            print('Token expired — refresh needed')
            # trigger token refresh flow
        else:
            raise PermissionError(
                f'API key rejected: {error.get("message", "401 Unauthorized")}'
            )
    response.raise_for_status()
    return response.json()

Verificação rápida: armazenamento de chave de API

Recapitulação da autenticação