Appi · Referencia

Autenticación

Registro, inicio de sesión con email o Google, verificación de correo y sesión actual.

Los usuarios de appi son globales: un mismo email puede participar en varios sitios. Cada vez que un usuario se registra o inicia sesión en tu sitio, appi crea (si no existe) su inscripción al sitio con rol user.

El login devuelve un token opaco tipo Bearer. Guárdalo del lado del servidor (por ejemplo en una cookie httpOnly) y envíalo en el header Authorization de cada petición que lo requiera.

Email y contraseña

POST/auth/register Público

Registrar un usuario

Crea la cuenta, la inscribe en tu sitio y envía un correo de bienvenida con un enlace de verificación válido por 24 horas. Al abrir el enlace, el usuario queda verificado y es redirigido a la URL configurada para tu sitio.

Cuerpo (JSON)
fullNamerequeridostring | nullNombre completo.
emailrequeridostringEmail válido, máximo 254 caracteres. Debe ser único.
passwordrequeridostringEntre 8 y 32 caracteres.
passwordConfirmationrequeridostringDebe coincidir con password.
Ejemplo de petición
{
  "fullName": "Ada Lovelace",
  "email": "[email protected]",
  "password": "unaClaveSegura",
  "passwordConfirmation": "unaClaveSegura"
}
Ejemplo de respuesta
{
  "user": { "id": "uuid", "fullName": "Ada Lovelace", "email": "[email protected]", "avatar": null },
  "enrollment": { "id": "uuid", "siteId": "uuid", "userId": "uuid", "role": "user" }
}
  • El usuario no puede iniciar sesión hasta verificar su correo.
POST/auth/send-verification-email Público

Reenviar correo de verificación

Cuerpo (JSON)
emailrequeridostringEmail del usuario.
Ejemplo de petición
{ "email": "[email protected]" }
Ejemplo de respuesta
{ "message": "Verification email sent. Please check your inbox." }
POST/auth/login Público

Iniciar sesión

Cuerpo (JSON)
emailrequeridostringEmail del usuario.
passwordrequeridostringContraseña.
Ejemplo de petición
{ "email": "[email protected]", "password": "unaClaveSegura" }
Ejemplo de respuesta
{
  "user": { "id": "uuid", "fullName": "Ada Lovelace", "email": "[email protected]", "avatar": null },
  "enrollment": { "id": "uuid", "role": "user" },
  "token": "oat_…"
}
  • Responde 400 con { "message": "Email not verified." } si el correo aún no fue verificado.
  • Unas credenciales inválidas responden con un error genérico, sin indicar si falló el email o la contraseña.
GET/auth/me Autenticado

Usuario de la sesión actual

Útil para hidratar el estado de sesión del frontend y conocer el rol del usuario en el sitio (user u owner).

Ejemplo de respuesta
{
  "user": { "id": "uuid", "fullName": "Ada Lovelace", "email": "[email protected]", "avatar": null, "emailVerifiedAt": "2026-01-01T00:00:00.000Z" },
  "enrollment": { "id": "uuid", "role": "user" }
}
  • Si el usuario aún no estaba inscrito en el sitio del header x-site-id, esta llamada lo inscribe con rol user.
GET/auth/sites Autenticado

Sitios del usuario

Lista todos los sitios en los que está inscrito el usuario, con su rol en cada uno. A diferencia del resto de rutas, no necesita x-site-id: úsala para construir un selector de sitio.

Ejemplo de respuesta
[
  {
    "id": "uuid",
    "siteId": "uuid",
    "userId": "uuid",
    "role": "owner",
    "site": { "id": "uuid", "name": "Mi sitio", "url": "https://misitio.com", "logo": null, "description": null }
  }
]
  • No requiere el header x-site-id y no modifica ninguna inscripción.
POST/auth/logout Autenticado

Cerrar sesión

Revoca el token usado en la petición.

Ejemplo de respuesta
{ "message": "Logged out successfully" }

Google OAuth

Flujo en dos pasos: pides la URL de autorización, rediriges al usuario y, cuando Google lo devuelve a tu callback con un code, lo intercambias por un token de appi. La URL de callback debe estar autorizada para el cliente OAuth de appi: solicítala junto con tu siteId.

GET/auth/google/url Público

Obtener la URL de autorización de Google

Query string
callbackUrlrequeridostringURL de tu frontend a la que Google devolverá al usuario.
Ejemplo de respuesta
{ "url": "https://accounts.google.com/o/oauth2/v2/auth?…" }
GET/auth/google/handle Público

Intercambiar el code de Google por un token

Si el email no existe, se crea la cuenta (ya verificada). En ambos casos se inscribe al usuario en tu sitio.

Query string
coderequeridostringCódigo que Google agregó a tu callback.
callbackUrlrequeridostringLa misma URL usada en el paso anterior.
Ejemplo de respuesta
{
  "user": { "id": "uuid", "fullName": "Ada Lovelace", "email": "[email protected]", "avatar": "https://…" },
  "enrollment": { "id": "uuid", "role": "user" },
  "token": "oat_…"
}

Información del sitio

GET/sites/:id Público

Datos públicos de un sitio

Nombre, URL, descripción y logo del sitio, útiles para la marca de tu frontend.

Parámetros de ruta
idrequeridostringTu siteId.
Ejemplo de respuesta
{ "id": "uuid", "name": "Mi sitio", "url": "https://misitio.com", "description": "…", "logo": "https://…" }