Autenticación

Todas las solicitudes de API de Archyl requieren autenticación usando una clave API. Esta guía explica cómo crear y usar claves API.

Creando una Clave API

1. Inicia sesión en tu cuenta de Archyl
2. Ve a Perfil > Claves API
3. Haz clic en Crear Clave API
4. Configura tu clave:
   • Nombre: Un nombre descriptivo (ej: "Pipeline CI/CD", "Desarrollo Local")
   • Permisos: Solo lectura o Lectura-Escritura
   • Expiración: Fecha de expiración opcional
5. Haz clic en Crear
6. Copia y guarda la clave inmediatamente - no se mostrará de nuevo

Permisos de Claves API

Elige los permisos mínimos requeridos para tu caso de uso.

Usando Tu Clave API

Incluye tu clave API en el encabezado X-API-Key con cada solicitud:

curl -H "X-API-Key: tu-clave-api" \
  https://api.archyl.com/api/v1/projects

Ejemplo: Listar Proyectos

curl -X GET \
  -H "X-API-Key: tu-clave-api" \
  -H "Content-Type: application/json" \
  https://api.archyl.com/api/v1/projects

Ejemplo: Crear un Sistema

curl -X POST \
  -H "X-API-Key: tu-clave-api" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Servicio de Pagos",
    "description": "Maneja el procesamiento de pagos",
    "type": "internal"
  }' \
  https://api.archyl.com/api/v1/projects/{projectId}/systems

Autenticación del Servidor MCP

Al usar el Servidor MCP con asistentes de IA, la autenticación funciona de la misma manera:

Claude Code / Claude Desktop

Agrega tu clave API a la configuración MCP:

{
  "mcpServers": {
    "archyl": {
      "url": "https://api.archyl.com/mcp",
      "headers": {
        "X-API-Key": "tu-clave-api"
      }
    }
  }
}

Cursor

En .cursor/mcp.json:

{
  "mcpServers": {
    "archyl": {
      "url": "https://api.archyl.com/mcp",
      "headers": {
        "X-API-Key": "tu-clave-api"
      }
    }
  }
}

Mejores Prácticas de Seguridad

Protege Tus Claves

• Nunca confirmes claves API en control de versiones
• Usa variables de entorno en pipelines CI/CD
• Rota las claves periódicamente
• Usa claves separadas para diferentes entornos

Variables de Entorno

# Almacenar en .env (agregar a .gitignore)
ARCHYL_API_KEY=tu-clave-api

# Usar en scripts
curl -H "X-API-Key: $ARCHYL_API_KEY" \
  https://api.archyl.com/api/v1/projects

Integración CI/CD

Almacena tu clave API como secreto en tu plataforma CI/CD:

GitHub Actions:

- name: Actualizar Arquitectura
  env:
    ARCHYL_API_KEY: ${{ secrets.ARCHYL_API_KEY }}
  run: |
    curl -X POST \
      -H "X-API-Key: $ARCHYL_API_KEY" \
      https://api.archyl.com/api/v1/projects/$PROJECT_ID/discover

GitLab CI:

update-architecture:
  script:
    - curl -X POST -H "X-API-Key: $ARCHYL_API_KEY" https://api.archyl.com/api/v1/projects/$PROJECT_ID/discover

Gestionando Claves API

Ver Claves

Ve a Perfil > Claves API para ver todas tus claves activas:

• Nombre y fecha de creación de la clave
• Nivel de permiso
• Estado de expiración
• Marca de tiempo de último uso

Revocar Claves

Para revocar una clave comprometida o sin usar:

1. Ve a Perfil > Claves API
2. Encuentra la clave a revocar
3. Haz clic en Revocar
4. Confirma la acción

Las claves revocadas son invalidadas inmediatamente.

Expiración de Claves

Las claves pueden configurarse para expirar:

• Nunca: La clave permanece válida hasta revocación manual
• 30 días: Bueno para acceso temporal
• 90 días: Equilibrio entre seguridad y conveniencia
• Personalizado: Establecer cualquier fecha de expiración

Respuestas de Error

Clave Inválida o Faltante

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Clave API inválida o faltante"
  }
}

Estado HTTP: 401 No Autorizado

Permisos Insuficientes

{
  "error": {
    "code": "FORBIDDEN",
    "message": "La clave API no tiene permisos de escritura"
  }
}

Estado HTTP: 403 Prohibido

Clave Expirada

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "La clave API ha expirado"
  }
}

Estado HTTP: 401 No Autorizado

Próximos Pasos

• Visión General de la API - Documentación completa de la API
• Servidor MCP - Integración con asistentes de IA