API de cuenta

Estas rutas solo están disponibles cuando FRAMEKIT_AUTH_ENABLED=true. Consulta la descripción general del acceso para conocer las reglas comunes de cookie, origen, solicitud y respuesta.

POST /api/framekit/login

Envía exactamente username y password:

{
  "username": "admin",
  "password": "your-password"
}

Usa la ruta de inicio de sesión desde un cliente del lado del servidor. Establece FRAMEKIT_ORIGIN en el origen de la solicitud y sustituye los marcadores de credenciales por los valores de la cuenta:

Node.js

const origin = process.env.FRAMEKIT_ORIGIN ?? 'http://localhost:3000'

const response = await fetch(`${origin}/api/framekit/login`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Origin: origin
  },
  body: JSON.stringify({
    username: 'admin',
    password: 'your-password'
  })
})

console.log(response.status, response.headers.get('set-cookie'))

curl

export FRAMEKIT_ORIGIN=http://localhost:3000

curl --fail-with-body --include \
  --request POST "$FRAMEKIT_ORIGIN/api/framekit/login" \
  --header 'Content-Type: application/json' \
  --header "Origin: $FRAMEKIT_ORIGIN" \
  --data '{"username":"admin","password":"your-password"}'

Si tiene éxito, la respuesta es 200, devuelve el objeto de usuario seguro y establece la cookie framekit_session:

{
  "id": "user-id",
  "username": "admin",
  "role": "admin"
}

Las credenciales inválidas, desconocidas o inactivas devuelven 401 unauthorized sin indicar qué caso ocurrió. Después de aceptar la forma de la solicitud, en una base de datos vacía esta ruta inicia el primer administrador usando FRAMEKIT_ADMIN_PASSWORD y el FRAMEKIT_ADMIN_USERNAME opcional (cuyo valor predeterminado es admin) antes de autenticarlo.

POST /api/framekit/logout

Devuelve 200 con:

{
  "status": "ok"
}

La respuesta hace caducar framekit_session. Repetir el cierre de sesión es seguro cuando no existe una sesión utilizable.

GET /api/framekit/account

Requiere una sesión y devuelve el objeto de usuario seguro con id, username y role.

PATCH /api/framekit/account

Requiere una mutación de sesión del mismo origen. Envía exactamente:

{
  "username": "new-name"
}

La respuesta es 200 con el objeto de usuario seguro actualizado. Los nombres de usuario tienen entre 3 y 64 letras ASCII, números, ., _ o -, y deben ser únicos sin distinguir mayúsculas y minúsculas.

POST /api/framekit/account/password

Requiere la sesión y la contraseña actuales. Envía exactamente:

{
  "currentPassword": "old-password",
  "newPassword": "new-password"
}

La contraseña nueva debe tener entre 12 y 256 bytes UTF-8. Un cambio correcto devuelve 200, { "status": "ok" } y una cookie de sesión caducada. Invalida todas las sesiones de esa cuenta, pero no revoca los tokens de API.