Autenticación, claves de API y organización
En esta página
Autenticación, claves de API y organización
Antes de escribir una sola línea de código, debes configurar tu acceso a la API. Esta lección explica cómo crear claves, estructurar el acceso mediante organizaciones y proyectos, y las precauciones de seguridad que evitan la pesadilla clásica: subir por error una clave a un repositorio público donde un desconocido la consuma durante la noche.
Crea tu cuenta y obtén una clave
El proceso consta de tres pasos. Primero, ve a platform.openai.com y crea una cuenta; recibirás automáticamente créditos gratuitos para empezar a experimentar. A continuación, navega hasta la sección API Keys del panel de control y genera una nueva clave. Solo verás esta clave una vez: cópiala de inmediato, pero no la pegues en tu código.
# Tu clave de API tiene este aspecto (¡nunca la compartas!)
# sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# Mejor práctica: usa una variable de entorno
import os
api_key = os.environ.get("OPENAI_API_KEY")
El tercer paso es declarar la variable de entorno, lo cual depende de tu plataforma. En una máquina de desarrollo, un archivo .env cargado por python-dotenv suele ser lo más cómodo. En un servidor, es preferible una variable de entorno definida por tu orquestador o servicio de secretos.
# Linux / macOS — añade a ~/.bashrc o ~/.zshrc
export OPENAI_API_KEY="sk-proj-your-key-here"
# Windows PowerShell
$env:OPENAI_API_KEY = "sk-proj-your-key-here"
# Archivo .env (con python-dotenv)
# .env
OPENAI_API_KEY=sk-proj-your-key-here
Qué tipo de clave elegir
Las claves de proyecto, identificables por su prefijo sk-proj-, están vinculadas a un proyecto específico y ofrecen el mejor control. Las usarás en casi todos los casos. El SDK las detecta automáticamente una vez establecida la variable de entorno; por eso OpenAI() se instancia sin argumentos en todos los ejemplos de este curso.
from openai import OpenAI
# El SDK detecta automáticamente OPENAI_API_KEY
client = OpenAI()
# O especifícala explícitamente (no recomendado para producción)
client = OpenAI(api_key="sk-proj-...")
Las claves de servicio son el segundo tipo. Diseñadas para aplicaciones de servidor que requieren acceso elevado, otorgan permisos adicionales y, por tanto, exigen un cuidado extra: guárdalas en una bóveda de secretos y nunca distribuyas su valor a una estación de trabajo de desarrollo.
Organizaciones y proyectos
El acceso se estructura en tres niveles anidados:
- Organización: tu empresa o equipo
- Proyecto: una agrupación lógica (por ejemplo, «Chatbot de producción», «Análisis de datos»)
- Clave de API: vinculada a un proyecto concreto
Si perteneces a varias organizaciones, especifica la que pretendes usar al instanciar el cliente:
from openai import OpenAI
# Especifica la organización (útil si perteneces a varias)
client = OpenAI(
organization="org-xxxxxxxxxxxx",
project="proj-xxxxxxxxxxxx"
)
Tómate el tiempo de dividir tu uso en proyectos en lugar de enrutarlo todo a través de una única clave. Verás el beneficio ante el primer indicio de problemas. Cada proyecto tiene su propio seguimiento de uso, lo que te permite atribuir costes a una funcionalidad específica en lugar de a un total mensual opaco. Los límites de tasa también se separan: un trabajo por lotes nocturno que sature su cuota no impedirá que tu chatbot responda a los clientes. Además, puedes asignar distintos miembros a cada proyecto y, lo que es más importante, revocar una clave comprometida sin interrumpir otras aplicaciones.
Nunca expongas tus claves
La regla es simple y absoluta: una clave nunca aparece en el código fuente. El contraste entre los dos fragmentos siguientes dice más que una larga disertación.
# MAL — clave hardcodeada en el código
client = OpenAI(api_key="sk-proj-abc123") # ¡PELIGRO!
# BIEN — variable de entorno
client = OpenAI() # Lee automáticamente OPENAI_API_KEY
# BIEN — archivo .env con python-dotenv
from dotenv import load_dotenv
load_dotenv()
client = OpenAI()
La consecuencia lógica afecta a tu .gitignore, que debe excluir los archivos de configuración locales antes de tu primer commit, no después. Una clave que se publica y luego se elimina sigue presente en el historial del repositorio.
# AÑADE SIEMPRE estas líneas a tu .gitignore
.env
.env.local
.env.production
*.key
Por último, planifica una rotación regular, cada 90 días. Puedes hacerlo sin tiempo de inactividad: crea una nueva clave, actualiza tus despliegues y, solo cuando nada la esté usando, elimina la antigua.
Verifica tu configuración
Antes de continuar, ejecuta este script. Comprueba la presencia de la clave, muestra una versión truncada para confirmar que es la correcta y, a continuación, realiza una llamada real. Vuelve a ejecutar esta prueba siempre que un entorno se comporte de forma extraña.
from openai import OpenAI
import os
def verify_configuration():
"""Verifica que la configuración de la API sea correcta."""
# Comprueba la clave
api_key = os.environ.get("OPENAI_API_KEY")
if not api_key:
print("ERROR: OPENAI_API_KEY no definida")
return False
print(f"Clave detectada: {api_key[:8]}...{api_key[-4:]}")
# Prueba la conexión
try:
client = OpenAI()
response = client.responses.create(
model="gpt-5.6-terra",
input="Reply only: OK"
)
print(f"Conexión correcta: {response.output_text}")
return True
except Exception as e:
print(f"ERROR de conexión: {e}")
return False
verify_configuration()
# Resultado esperado:
# Clave detectada: sk-proj-...xxxx
# Conexión correcta: OK
Puntos clave
- Usa claves de proyecto (
sk-proj-...) para cada aplicación - Almacena tus claves en variables de entorno, nunca en el código
- Organiza tu acceso con la jerarquía Organización → Proyecto → Clave
- Realiza una rotación regular de tus claves (cada 90 días)
- Añade siempre
.enva tu.gitignore