API Reference

Referencia resumida del backend .NET que aparece en los adjuntos. La fuente de verdad para los contratos completos sigue siendo el README.md y API.md del repositorio backend; esta página organiza lo más importante para navegar el sistema desde la documentación.

Convenciones generales

• Base URL local: http://localhost:5133
• Formato de respuesta normal: ServiceResponse<T>
• Auth: Authorization: Bearer <jwt> en todo lo que no sea público
• CORS: se configura con Frontend:Origins o Frontend:BaseUrl
• Rate limiting: existe por IP, por usuario y por operación sensible

Ejemplo de respuesta:

{
  "success": true,
  "message": "ok",
  "data": {}
}

Flujo de autenticación

La API soporta dos caminos principales:

1. Email y contraseña: POST /api/auth/register y POST /api/auth/login.
2. OAuth: GET /api/auth/login/google o GET /api/auth/login/github.

En OAuth, el backend termina redirigiendo a una ruta del frontend con el token en el hash:

/auth/callback#access_token=<jwt>&expires_at=<iso8601>&provider=<Google|GitHub>

El frontend debe leer window.location.hash, no query params.

Endpoints públicos

Método	Ruta	Uso
GET	/api/metrics/platform	Métricas globales para la portada
GET	/api/engines	Catálogo de motores disponibles
GET	/api/auth/login/{provider}	Inicia OAuth
GET	/api/auth/callback/{provider}	Finaliza OAuth y redirige al frontend
POST	/api/auth/register	Registro con email y contraseña
POST	/api/auth/login	Login con email y contraseña
POST	/api/auth/forgot-password	Recuperación de contraseña local

Respuesta de register / login

Devuelven el JWT y el usuario autenticado:

{
  "success": true,
  "message": "User registered successfully.",
  "data": {
    "accessToken": "eyJhbGciOi...",
    "tokenType": "Bearer",
    "expiresAt": "2026-08-13T15:30:00Z",
    "provider": "Password",
    "user": {
      "id": 7,
      "name": "Jane Doe",
      "email": "jane@correo.com",
      "role": "User",
      "provider": "",
      "providerUserId": ""
    }
  }
}

Mis recursos

Estas rutas usan el usuario autenticado del JWT.

Método	Ruta	Uso
GET	/api/me/databases	Lista las bases del usuario
POST	/api/me/databases	Crea una base para el usuario
POST	/api/me/databases/{id}/pause	Pausa una base propia
POST	/api/me/databases/{id}/resume	Reanuda una base propia
DELETE	/api/me/databases/{id}	Elimina una base propia
GET	/api/me/databases/{id}/password	Revela la contraseña de una base propia
GET	/api/me/n8n	Lista cuentas N8N propias
POST	/api/me/n8n/provision	Solicita aprovisionamiento N8N
GET	/api/me/dns	Lista registros DNS propios
POST	/api/me/dns	Solicita aprovisionamiento DNS
DELETE	/api/me/dns/{id}	Revoca un registro DNS propio
GET	/api/me/ai-keys	Lista API keys de IA
POST	/api/me/ai-keys	Crea una API key de IA
POST	/api/me/ai-keys/{id}/rotate	Rota una API key de IA
DELETE	/api/me/ai-keys/{id}	Revoca una API key de IA

Bases de datos

GET /api/me/databases devuelve objetos con campos como:

• databaseInstanceId
• host
• port
• databaseName
• databaseUser
• engine
• status
• usedSpaceBytes
• maxSpaceBytes
• lastActivity

El endpoint de contraseña está rate-limited y se audita.

N8N

El backend guarda el estado local y luego llama a la célula externa configurada con N8nProvisioning.

DNS

La célula DNS persiste en SQL Server y luego llama a Cloudflare API v4.

IA

La IA se divide entre:

• gestión de keys con JWT;
• generación con X-API-Key.

Administración

Estas rutas requieren rol Admin.

Método	Ruta	Uso
GET/POST/PUT/DELETE	/api/users*	CRUD de usuarios
GET/POST/PUT/DELETE	/api/database-instances*	CRUD de bases
GET/POST/PUT/DELETE	/api/access-credentials*	CRUD de credenciales
GET/POST/PUT/DELETE	/api/audit-events*	CRUD de auditoría
GET	/api/users/{userId}/dashboard	Dashboard de otro usuario
GET/POST	/api/n8n/accounts*	Administración de cuentas N8N
GET/POST	/api/dns/records*	Administración de registros DNS

Errores a manejar

Código	Cuándo
400	Request inválido o validación del modelo
401	Falta token, token inválido o login fallido
403	Falta rol Admin
404	Recurso inexistente o ajeno
409	Conflicto de negocio
429	Rate limit excedido
500	Error no controlado

Qué leer después

• Frontend Flutter
• DNS y Cloudflare
• Ciclo de vida de bases