Proteger un endpoint con API Keys en Serverless Framework es una de las formas más rápidas de controlar quién accede a tus recursos en AWS sin escribir lógica adicional. Aquí verás cómo declarar un endpoint como privado, generar la llave automáticamente y validarla desde Postman, todo dentro de un flujo CI/CD con GitHub Actions.

¿Qué hace privado a un endpoint en API Gateway?

Un endpoint privado en API Gateway es aquel que rechaza cualquier petición que no incluya una llave alfanumérica válida en sus headers. La validación la hace API Gateway por ti, sin tocar tu función Lambda.

Para marcar un endpoint como privado dentro del archivo de configuración de Serverless Framework, basta con agregar la propiedad private: true dentro del evento HTTP de la función. En el ejemplo de la clase, el endpoint getUsers se configura así para que toda petición pase primero por el filtro de API Gateway.

¿Qué es una API Key? Es una llave alfanumérica que API Gateway valida en cada petición para decidir si permite o no el acceso a un recurso marcado como privado.

¿Cómo se declara la API Key en el provider?

Dentro de la sección provider del archivo serverless.yml, se añade el bloque apiGateway y dentro de él la lista apiKeys. Ahí defines el nombre de la llave, normalmente combinando el nombre del servicio con un sufijo identificador.

Usar Visual Studio Code con plugins de autocompletado del ecosistema serverless ayuda mucho, porque sugiere las propiedades válidas y reduce errores de tipeo en el YAML.

¿Cómo se despliega la API Key con GitHub Actions?

Cuando el proyecto ya tiene un flujo de CI/CD configurado, basta con hacer commit y push para que la automatización se encargue del resto. GitHub Actions detecta el cambio, ejecuta los flujos de testing, construye la layer y dispara el despliegue mediante CloudFormation.

Durante el despliegue, CloudFormation actualiza varios recursos en orden:

• Las Lambda layers asociadas al servicio.
• Las funciones Lambda definidas en el proyecto.
• Los eventos vinculados a API Gateway, incluyendo la nueva configuración privada.
• La generación automática de la API Key declarada en el provider.

Mientras el despliegue no termina, el endpoint sigue respondiendo 200 OK. En cuanto CloudFormation aplica los cambios, la misma petición empieza a devolver 403 Forbidden.

¿Y si quisiera crear la API Key manualmente?

En la consola de AWS puedes entrar a tu API dentro de API Gateway y buscar la sección API Keys al final del menú. Ahí tienes opciones para importar llaves o crearlas indicando nombre, si es autogenerada o personalizada, y una descripción.

Es el mismo conjunto de clics que Serverless Framework automatiza con un par de líneas en el YAML. Conocer el flujo manual sirve para depurar o para casos donde necesites una llave fuera del despliegue automatizado.

¿Cómo se usa la API Key desde Postman?

Una vez terminado el despliegue, la salida de consola muestra un apartado nuevo además de los endpoints, funciones y layers: el valor de la API Key generada automáticamente. Ese valor es el que vas a usar como credencial.

En Postman, el procedimiento es directo:

1. Abre la pestaña Headers de la petición.
2. Agrega un header llamado X-API-Key.
3. Pega como valor la llave que devolvió el deploy.
4. Habilita el header con el check lateral, porque Postman no lo envía si está desmarcado.
5. Envía la petición con send.

¿Por qué mi petición sigue dando 403 aunque puse la API Key? Probablemente el header X-API-Key no está habilitado en Postman, o la Lambda aún no termina de propagarse a todas las regiones tras el despliegue. Espera unos segundos y revisa el check del header.

Con la llave correctamente enviada, el endpoint vuelve a responder con los datos esperados. Si quieres confirmar que un usuario existe, puedes ir a DynamoDB, copiar un ID y usarlo como parámetro en la petición.

¿Dónde se ve la API Key generada en AWS?

Después del despliegue, entras a API Gateway en la consola de AWS, seleccionas tu API y vas a la sección API Keys. Ahí aparece la llave creada por Serverless Framework con el nombre que definiste en el archivo de configuración.

Esta verificación cierra el ciclo: declaraste la llave en código, GitHub Actions disparó el despliegue, CloudFormation creó el recurso y AWS lo expone listo para usarse.

¿Es seguro autenticar solo con API Keys?

Las API Keys son un buen primer filtro, pero no sustituyen mecanismos más robustos como un custom authorizer, que permite validar tokens, roles y lógica personalizada antes de dejar pasar la petición.

¿Te parece viable usar solo API Keys para tus endpoints o prefieres combinarlas con un custom authorizer? Cuéntame en los comentarios cómo manejas la autenticación en tus proyectos serverless.