API Keys

Las API keys son tokens de autenticacion que permiten acceder a Almirant desde herramientas externas, scripts o integraciones programaticas. Son el mecanismo principal para conectar clientes MCP como Claude Code, automatizaciones CI/CD o cualquier servicio que necesite interactuar con la API de Almirant.

Para que sirven

Las API keys se usan principalmente para:

• Conectar Claude Code -- Autenticar el servidor MCP de Almirant para que Claude Code pueda gestionar proyectos, boards y work items. Consulta la guia de Autenticacion MCP para mas detalles.
• Automatizaciones -- Scripts o pipelines de CI/CD que crean work items, actualizan estados o registran sesiones de IA.
• Integraciones custom -- Aplicaciones propias que interactuan con la API de Almirant.

Generar una API key

1. Accede a Configuracion > API Keys.
2. Haz clic en Generar nueva API Key.
3. Introduce un nombre descriptivo para identificar el proposito de la key (por ejemplo: "Claude Code - Laptop trabajo", "CI/CD Pipeline", "Bot interno").
4. Selecciona los permisos que tendra la key.
5. Haz clic en Crear.
6. Copia la API key inmediatamente.

Copia la key ahora

La API key completa solo se muestra una vez en el momento de crearla. Si cierras el dialogo sin copiarla, no podras recuperarla y tendras que generar una nueva.

Usar la API key

Las API keys se envian en la cabecera Authorization con el esquema Bearer:

curl -H "Authorization: Bearer tu-api-key-aqui" \
  https://api.almirant.ai/api/projects

Configuracion para MCP (Claude Code)

Para usar la API key con el servidor MCP de Almirant en Claude Code, anade la siguiente configuracion al archivo .mcp.json de tu proyecto:

{
  "mcpServers": {
    "almirant": {
      "type": "http",
      "url": "https://api.almirant.ai/mcp?projectId=uuid-del-proyecto",
      "headers": {
        "Authorization": "Bearer tu-api-key-aqui"
      }
    }
  }
}

Para desarrollo local, reemplaza la URL con http://localhost:3001/mcp?projectId=uuid-del-proyecto.

Consulta la referencia completa de Autenticacion MCP y Project Scoping para mas opciones de configuracion.

Gestionar API keys

Ver keys existentes

Desde Configuracion > API Keys puedes ver la lista de todas las keys generadas con:

Campo	Descripcion
Nombre	Nombre descriptivo asignado al crear la key
Prefijo	Primeros caracteres de la key para identificarla (el resto esta oculto)
Fecha de creacion	Cuando se genero la key
Ultimo uso	Fecha de la ultima peticion autenticada con esta key

Revocar una API key

Si una API key se ve comprometida o ya no es necesaria:

1. Accede a Configuracion > API Keys.
2. Busca la key en la lista.
3. Haz clic en Revocar.
4. Confirma la revocacion.

peligro

Revocar una API key es inmediato e irreversible. Cualquier servicio o herramienta que use esa key dejara de funcionar al instante. Asegurate de actualizar las configuraciones de los servicios afectados antes de revocar.

Buenas practicas de seguridad

Seguridad de API keys

Las API keys proporcionan acceso a los datos de tu organizacion. Tratalas con el mismo nivel de seguridad que una contrasena.

• Una key por servicio -- Genera una API key diferente para cada herramienta o servicio. Si una se compromete, puedes revocarla sin afectar al resto.
• Nombres descriptivos -- Usa nombres que identifiquen claramente donde se usa la key: "Claude Code - PC oficina", "GitHub Actions - Deploy", "Bot Slack - Notificaciones".
• No compartas keys -- Cada miembro del equipo que necesite acceso MCP deberia generar su propia API key.
• No incluyas keys en el codigo -- Nunca commits API keys en repositorios de codigo. Usa variables de entorno o gestores de secretos.
• Revisa periodicamente -- Revoca las keys que ya no se usan o cuyo proposito desconoces.
• Rota keys comprometidas -- Si sospechas que una key se ha filtrado, revocala inmediatamente y genera una nueva.

Ejemplo de uso seguro con variables de entorno

En lugar de escribir la key directamente en archivos de configuracion:

# .env (excluido de git via .gitignore)
ALMIRANT_API_KEY=tu-api-key-aqui

// .mcp.json (usa referencia a variable de entorno si tu herramienta lo soporta)
{
  "mcpServers": {
    "almirant": {
      "type": "http",
      "url": "https://api.almirant.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${ALMIRANT_API_KEY}"
      }
    }
  }
}

Para Developers

Arquitectura de autenticacion

Las API keys se almacenan de forma hasheada en la tabla apiKeys del schema de base de datos. El flujo de autenticacion es:

1. El cliente envia la API key en la cabecera Authorization: Bearer <key>.
2. El backend busca la key hasheada en la tabla apiKeys.
3. Si la key es valida, se obtiene el usuario y la organizacion asociados.
4. El contexto de autenticacion ({ user, organizationId }) se inyecta en la peticion.
5. Las rutas protegidas usan este contexto para filtrar datos por organizacion.

Endpoints relevantes

Metodo	Ruta	Descripcion
GET	/api/api-keys	Lista las API keys de la organizacion
POST	/api/api-keys	Genera una nueva API key
DELETE	/api/api-keys/:id	Revoca una API key

Permisos y scopes

Las API keys heredan los permisos del usuario que las creo. El alcance de la key esta limitado a la organizacion del usuario.