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

Inicia sesión en tu cuenta de Archyl
Ve a Perfil > Claves API
Haz clic en Crear Clave API
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
Haz clic en Crear
Copia y guarda la clave inmediatamente - no se mostrará de nuevo

Permisos de Claves API

Permiso	Capacidades
Lectura	Ver proyectos, elementos, documentación y datos de arquitectura
Escritura	Crear, modificar y eliminar proyectos, elementos y documentación

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/sse",
      "headers": {
        "X-API-Key": "tu-clave-api"
      }
    }
  }
}

Cursor

En .cursor/mcp.json:

{
  "mcpServers": {
    "archyl": {
      "url": "https://api.archyl.com/sse",
      "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:

Ve a Perfil > Claves API
Encuentra la clave a revocar
Haz clic en Revocar
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"
  }
}