API keys y variables de entorno en Claude Code

Qué son las API keys y por qué deberías protegerlas

Tarde o temprano, cualquier proyecto con Claude Code necesita conectarse a un servicio externo: enviar correos, procesar pagos, consultar datos meteorológicos o usar inteligencia artificial. Para acceder a esos servicios necesitas una API key, y cómo la guardes puede ser la diferencia entre un proyecto seguro y una factura sorpresa de miles de euros.

Una API key es como la tarjeta de acceso de un hotel. El hotel (el servicio) te la entrega cuando te registras. Cada vez que quieres entrar a tu habitación (hacer una petición), pasas la tarjeta. Si alguien la copia, puede entrar como si fuera tú, y el hotel te cobrará todo lo que consuma.

El error que todo principiante comete

El instinto natural es escribir la clave directamente en el código:

const apiKey = "sk-abc123456789"

Esto funciona. Tu aplicación se conecta al servicio y todo va bien. Hasta que subes el código a GitHub y esa clave queda visible para cualquiera que tenga acceso al repositorio. Bots automáticos escanean GitHub constantemente buscando claves expuestas. En minutos, alguien puede estar usando tu cuenta.

La solución: variables de entorno y archivo .env

Las variables de entorno son valores que existen fuera de tu código. Tu aplicación los lee cuando se ejecuta, pero nunca aparecen escritos en los archivos del proyecto. El estándar de la industria es guardarlas en un archivo llamado .env.

Paso 1: crear el archivo .env

Dile a Claude Code:

Crea un archivo .env en la raíz del proyecto

Claude creará un archivo donde cada línea tiene el formato NOMBRE=valor:

OPENAI_API_KEY=sk-abc123456789
RESEND_API_KEY=re_xyz987654321
DATABASE_URL=postgresql://usuario:clave@servidor/base

Paso 2: proteger el archivo con .gitignore

El archivo .env contiene tus secretos. Nunca debe subirse a GitHub. Para evitarlo, existe un archivo llamado .gitignore que le dice a git qué archivos ignorar.

Dile a Claude:

Añade .env al archivo .gitignore

Claude se asegurará de que tu archivo .gitignore incluya la línea .env. A partir de ese momento, git ignorará el archivo por completo. No aparecerá en tus commits ni se subirá a GitHub.

Paso 3: usar las variables en tu código

En vez de escribir la clave directamente, tu código la lee del entorno:

const apiKey = process.env.OPENAI_API_KEY

Cuando la aplicación se ejecuta, busca la variable OPENAI_API_KEY en el entorno (que cargó desde tu archivo .env). El código nunca contiene el valor real. Si alguien lee tu código, solo ve el nombre de la variable, no la clave.

Paso 4: crear un archivo .env.example

Para que otros (o tú mismo en otro ordenador) sepan qué variables necesita el proyecto, crea un archivo de ejemplo:

Crea un archivo .env.example con los nombres de las variables pero sin los valores reales

Claude generará algo así:

OPENAI_API_KEY=tu-clave-aqui
RESEND_API_KEY=tu-clave-aqui
DATABASE_URL=tu-url-aqui

Este archivo sí se sube a GitHub. Sirve como documentación: cualquiera que clone el proyecto sabe qué claves necesita configurar.

Dónde conseguir tus API keys

Cada servicio tiene su propio panel de gestión. Aquí tienes los más comunes:

Variables de entorno en producción

Cuando despliegas tu aplicación (por ejemplo en Vercel), no puedes subir un archivo .env al servidor. En su lugar, configuras las variables directamente en la plataforma de despliegue.

En Vercel, por ejemplo, vas a los ajustes del proyecto y añades cada variable con su valor. La plataforma las inyecta de forma segura cuando tu aplicación se ejecuta. El resultado es el mismo: tu código lee process.env.NOMBRE y obtiene el valor, sin que la clave aparezca en ningún archivo público.

Puedes pedirle a Claude Code que te ayude con esto:

Añade la variable OPENAI_API_KEY a Vercel con el valor que tengo en .env

Resumen: la regla de oro

Nunca escribas una clave directamente en tu código. Siempre usa variables de entorno. Siempre protege tu .env con .gitignore. Es un hábito que te ahorrará problemas serios, y con Claude Code, configurarlo toma menos de un minuto.

Para profundizar en cómo proteger tu proyecto completo, lee nuestra guía sobre desarrollo de apps seguras con Claude Code.

Siguiente lectura: Instalar community skills en Claude Code | Ver la guía completa