AI Agents · Lección

Autenticación: claves de API y OAuth

Tokens Bearer, cabeceras de claves de API y flujos OAuth2 para acceder a las API de agentes.

Lección 2 de 413 pasos

Autenticación: claves de API y OAuth es una lección gratuita de AI Agents en CoddyKit. Esta es la lección 2 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de AI Agents, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de AI Agents incluye 4 lecciones en total.

Por qué es importante la autenticación para los agentes

Cuando su agente llama a una API externa, el servidor necesita saber quién realiza la solicitud. La autenticación demuestra la identidad; la autorización determina qué puede hacer. Sin una autenticación adecuada, todas las solicitudes devuelven 401 Unauthorized y su agente no puede hacer nada.

En el desarrollo de agentes predominan dos patrones: las claves de API y OAuth 2.0.

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

Clave de API en el encabezado Authorization

El patrón más habitual consiste en enviar la clave de API en el encabezado Authorization como un token Bearer. La palabra «Bearer» indica que quien posee este token está autorizado; el servidor confía en quien presenta la clave.

OpenAI, Anthropic, GitHub y la mayoría de las API modernas utilizan este patrón.

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'])

Clave de API en un encabezado personalizado (X-API-Key)

Algunas API, especialmente las más antiguas o internas, utilizan un encabezado personalizado como X-API-Key en lugar de Authorization: Bearer. El patrón es el mismo, solo cambia el nombre del encabezado. Consulte siempre la documentación de la API para conocer el nombre exacto del encabezado esperado.

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')

Almacenar credenciales en variables de entorno

No incluya nunca claves de API directamente en el código fuente. Si confirma una clave en un repositorio público, los bots la encontrarán y abusarán de ella en cuestión de segundos. El patrón correcto consiste en almacenar las credenciales en variables de entorno y leerlas durante la ejecución con os.environ.

Utilice os.environ.get() y muestre un mensaje de error claro si falta la clave.

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)')

Usar python-dotenv durante el desarrollo local

Durante el desarrollo, guarde las claves en un archivo .env en la raíz del proyecto. Utilice la biblioteca python-dotenv para cargarlas automáticamente. Añada .env a .gitignore para evitar que se confirme.

# .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')

¿Qué es OAuth 2.0?

OAuth 2.0 es un estándar para la autorización delegada. En lugar de proporcionar al agente la contraseña del usuario, OAuth permite que el usuario autorice a su agente a actuar en su nombre, con un alcance y un periodo de validez limitados. Lo utilizan Google, GitHub, Slack y Salesforce.

El concepto clave es que su agente obtiene un token de acceso después de un flujo de autorización y utiliza ese token para realizar llamadas a la API.

# 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')

Flujo de credenciales de cliente de OAuth2

El flujo de credenciales de cliente es el flujo de OAuth más sencillo para los agentes: no requiere interacción del usuario. Su agente se autentica con su propio ID de cliente y secreto para obtener un token. Se utiliza para la comunicación entre máquinas (M2M).

Envíe sus credenciales mediante POST al endpoint de tokens y recibirá un token de acceso de corta duración.

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')

Uso de tokens OAuth en llamadas a la API

Cuando tenga un token de acceso OAuth, utilícelo exactamente como una clave de API: en el encabezado Authorization: Bearer. La diferencia es que los tokens OAuth caducan, por lo que su agente debe gestionar la renovación del token antes de realizar llamadas.

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 con la biblioteca google-auth

Para las API de Google, la biblioteca google-auth gestiona toda la complejidad de OAuth por usted. Administra automáticamente la renovación de tokens, lee las credenciales de un archivo JSON y adjunta los tokens a las solicitudes mediante una AuthorizedSession.

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())

Buenas prácticas de seguridad para claves de API

Proteger las claves de API es fundamental para la seguridad de los agentes. Siga estas reglas:

  • Almacene las claves en variables de entorno o en un gestor de secretos (AWS Secrets Manager, HashiCorp Vault)
  • No registre nunca las claves; enmascárelas en la salida
  • Rote las claves periódicamente y revoque de inmediato las que se hayan visto comprometidas
  • Utilice el principio de mínimo privilegio: solicite únicamente los scopes que su agente necesite
  • Configure listas de IP permitidas para las claves de API cuando el proveedor lo admita
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)}')

Gestión de 401 Unauthorized en su agente

Cuando un agente recibe una respuesta 401 Unauthorized, nunca debe reintentarlo a ciegas, ya que desperdicia la cuota del límite de solicitudes. En su lugar, compruebe si el token ha caducado (intente renovarlo) o si la propia clave no es válida (alerte de inmediato para que una persona pueda corregirlo).

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()

Comprobación rápida: almacenamiento de claves de API

Compruebe cuánto ha comprendido sobre la gestión de credenciales.

Resumen de autenticación

Ha aprendido los dos patrones principales de autenticación para agentes:

  • Claves de API: se envían en el encabezado Authorization: Bearer TOKEN o X-API-Key; son sencillas y sin estado
  • OAuth 2.0: flujo de credenciales de cliente para M2M; los tokens caducan y deben renovarse
  • Almacene siempre las claves en variables de entorno, nunca en el código fuente
  • Utilice python-dotenv localmente; en producción, use variables de entorno o gestores de secretos
  • Gestione las respuestas 401 comprobando si el token ha caducado o si la clave no es válida

Una gestión sólida de la autenticación es la base de todo agente fiable.

Gratis para empezar

Aprende AI Agents con un tutor de IA — gratis

Escribe y ejecuta código real en tu navegador, obtén ayuda instantánea de un tutor de IA disponible 24/7 y continúa donde lo dejaste en la web o en la aplicación.

Cursos
60
Lecciones
239

Preguntas frecuentes

¿La lección «Autenticación: claves de API y OAuth» es gratis?

Sí — el texto completo de «Autenticación: claves de API y OAuth» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de AI Agents, actualiza a CoddyKit PRO. El curso de AI Agents incluye 4 lecciones en total.

¿Qué aprenderé en «Autenticación: claves de API y OAuth»?

Tokens Bearer, cabeceras de claves de API y flujos OAuth2 para acceder a las API de agentes. Practicas AI Agents con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar AI Agents?

No se requiere experiencia previa. AI Agents en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 2 de 4.

¿Cuánto tiempo toma la lección «Autenticación: claves de API y OAuth»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de AI Agents?

Sí. Cada lección de AI Agents incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

  1. Fundamentos de REST API para desarrolladores de agentes
  2. Autenticación: claves de API y OAuth
  3. Gestión de respuestas y errores de API
  4. Limitación de velocidad y lógica de reintentos
← Volver a AI Agents