Autenticación y permisos
La API de ChurchApps usa autenticación basada en JWT. Los usuarios inician sesión para recibir un token que codifica su identidad, su pertenencia a iglesias y sus permisos. Esta página cubre el flujo de autenticación, el modelo de permisos y el soporte de OAuth.
Flujo de inicio de sesión
Inicio de sesión estándar
POST /membership/users/login
Autenticación: Pública
Acepta uno de tres tipos de credenciales:
| Campo | Descripción |
|---|---|
email + password | Inicio de sesión estándar con correo electrónico y contraseña |
jwt | Volver a autenticarse con un JWT existente |
authGuid | Enlace de autenticación de un solo uso (usado en correos de bienvenida y restablecimiento) |
Respuesta:
{
"user": {
"id": "abc-123",
"firstName": "Jane",
"lastName": "Doe",
"email": "jane@example.com"
},
"churches": [
{
"church": { "id": "church-1", "name": "First Church", "subDomain": "firstchurch" },
"person": { "id": "person-1", "membershipStatus": "Member" },
"groups": [{ "id": "group-1", "name": "Choir", "leader": false }],
"apis": [
{
"keyName": "MembershipApi",
"permissions": [
{ "contentType": "People", "action": "View" },
{ "contentType": "People", "action": "Edit" }
]
}
]
}
],
"token": "<jwt-token>"
}
El campo token es un JWT que debe enviarse como Authorization: Bearer <token> en las solicitudes siguientes.
Verificación en dos pasos
Los usuarios pueden activar la verificación en dos pasos con una aplicación de autenticación (TOTP). Para esos usuarios, un inicio de sesión con email + password, authGuid o SSO no devuelve un token. En su lugar, responde con un desafío:
{ "mfaRequired": true, "mfaToken": "<challenge-token>" }
El token de desafío es válido durante 5 minutos. Envíelo de vuelta al mismo endpoint junto con el código:
{ "mfaToken": "<challenge-token>", "mfaCode": "123456" }
mfaCode puede ser el código de 6 dígitos vigente de la aplicación de autenticación o uno de los diez códigos de respaldo de un solo uso del usuario. Un código incorrecto devuelve Invalid code, y los intentos fallidos repetidos se limitan por cuenta. Un inicio de sesión con jwt nunca se desafía, así que las sesiones existentes siguen renovándose. El objeto user de la respuesta de inicio de sesión incluye mfaEnabled.
Endpoints de autoservicio (solo para el usuario con sesión iniciada, bajo /membership/users/mfa):
| Endpoint | Descripción |
|---|---|
GET /status | { enabled, backupCodesLeft } |
POST /setup | Inicia la configuración; devuelve { secret, otpauthUrl } para el código QR |
POST /enable | Cuerpo { code }; la activa y devuelve { backupCodes } una sola vez |
POST /disable | Cuerpo { code } (código de la aplicación o de respaldo); la desactiva |
POST /reset/:userId | Solo Server.Admin; la desactiva para otro usuario |
Los secretos se guardan cifrados y los códigos de respaldo se guardan como hashes. Activar, desactivar y restablecer se escriben en el registro de auditoría.
Contenido del token
El JWT codifica:
id: ID del usuariochurchId: iglesia seleccionada actualmentepersonId: registro de persona de la iglesia seleccionada- Arreglos de permisos por API
Selección de iglesia
Los usuarios pueden pertenecer a varias iglesias. La respuesta de inicio de sesión incluye todas las iglesias con sus permisos. Para cambiar de iglesia, el cliente genera un nuevo JWT limitado a otra iglesia a partir de los datos de la respuesta de inicio de sesión.
Registro de usuarios
Registrar un nuevo usuario
POST /membership/users/register
Autenticación: Pública
{
"email": "jane@example.com",
"firstName": "Jane",
"lastName": "Doe",
"appName": "B1 Admin",
"appUrl": "https://app.b1.church"
}
Crea un usuario con una contraseña temporal y envía un correo de bienvenida con un enlace de autenticación. El primer usuario registrado en una instancia nueva recibe automáticamente acceso de administrador del servidor.
Se aceptan dos campos opcionales de trampa para bots: website (un campo oculto de tipo honeypot que los usuarios reales dejan vacío) y fillMs (cuánto tiempo estuvo abierto el formulario, en milisegundos). Si website tiene contenido o si fillMs es menor que 2000, no se crea ninguna cuenta, pero el endpoint sigue devolviendo un 200 con apariencia normal para que los bots no puedan saber que fueron rechazados. Los clientes que omiten ambos campos se registran como de costumbre.
Registrar una nueva iglesia
POST /membership/churches/add
Autenticación: JWT
Después de registrar un usuario, llame a este endpoint para crear una iglesia y asociar al usuario con ella.
Administración de contraseñas
| Método | Ruta | Autenticación | Descripción |
|---|---|---|---|
| POST | /membership/users/forgot | Pública | Envía un correo de restablecimiento de contraseña. Cuerpo: { "userEmail": "...", "appName": "...", "appUrl": "..." } |
| POST | /membership/users/setPasswordGuid | Pública | Establece una nueva contraseña con un GUID de autenticación del correo de restablecimiento. Cuerpo: { "authGuid": "...", "newPassword": "..." } |
| POST | /membership/users/updatePassword | JWT | Cambia la contraseña del usuario actual. Cuerpo: { "newPassword": "..." } |
Modelo de permisos
Los permisos se organizan por módulo y se asignan a los usuarios mediante roles. Cada permiso tiene un tipo de contenido y una acción.
Referencia de permisos
| Sección visible | Tipo de contenido | Acción | Descripción |
|---|---|---|---|
| Attendance | Attendance | Checkin | Registrar la entrada de miembros en los servicios |
| Attendance | Edit | Editar registros de asistencia | |
| Services | Edit | Administrar servicios y horarios de servicio | |
| Attendance | View | Ver registros de asistencia | |
| Attendance | View Summary | Ver resúmenes e informes de asistencia | |
| Donations | Donations | Edit | Crear y editar registros de donaciones |
| Settings | Edit | Editar la configuración de ofrendas y pagos | |
| Donations | View Summary | Ver informes resumidos de donaciones | |
| Donations | View | Ver registros individuales de donaciones | |
| People and Groups | Forms | Admin | Administración completa de formularios |
| Forms | Edit | Editar definiciones de formularios | |
| Plans | Edit | Editar planes de servicio | |
| Group Members | Edit | Agregar o quitar miembros de grupos | |
| Groups | Edit | Crear y editar grupos | |
| Households | Edit | Editar las asignaciones de hogares | |
| People | Edit | Editar cualquier registro de persona | |
| People | Edit Self | Editar solo su propio registro de persona | |
| Roles | Edit | Administrar roles y asignaciones de usuarios | |
| Group Members | View | Ver listas de miembros de grupos | |
| People | View Members | Ver solo miembros (no visitantes) | |
| People | View | Ver todas las personas | |
| Roles | View | Ver roles y asignaciones | |
| Settings | Edit | Editar la configuración de la iglesia | |
| Content | Content | Edit | Editar páginas, secciones y elementos |
| Settings | Edit | Editar la configuración de contenido | |
| StreamingServices | Edit | Administrar la configuración de los servicios de transmisión | |
| Chat | Host | Organizar y moderar sesiones de chat | |
| Messaging | Texting | Send | Enviar mensajes de texto SMS |
Cómo se verifican los permisos
En los controladores, los permisos se verifican con el método au.checkAccess():
// Exigir un permiso específico
if (!au.checkAccess(Permissions.people.edit)) return this.json({}, 401);
// O dentro de actionWrapper: el sistema CRUD verifica automáticamente
crudSettings: {
permissions: {
view: Permissions.people.view,
edit: Permissions.people.edit
}
}
Administrador del servidor
El permiso Server.Admin concede acceso completo a todas las iglesias. Se asigna al primer usuario registrado y puede otorgarse a otros mediante el rol de administrador del servidor.
OAuth 2.0
La API admite OAuth 2.0 para integraciones de terceros. Hay dos tipos de concesión disponibles.
Flujo de código de autorización
-
Autorizar:
POST /membership/oauth/authorize(requiere JWT)- Cuerpo:
{ "client_id": "...", "redirect_uri": "...", "response_type": "code", "scope": "...", "state": "...", "code_challenge": "...", "code_challenge_method": "S256" } code_challenge/code_challenge_method(PKCE, soloS256) son obligatorios para clientes públicos sin secreto- Devuelve:
{ "code": "...", "state": "..." }
- Cuerpo:
-
Intercambiar el código por un token:
POST /membership/oauth/token(Pública)- Cuerpo:
{ "grant_type": "authorization_code", "code": "...", "client_id": "...", "client_secret": "...", "redirect_uri": "...", "code_verifier": "..." } - Envíe
code_verifiercuando el paso de autorización usó uncode_challenge; los clientes públicos omitenclient_secret. Se aceptan cuerpos JSON o codificados como formulario - Devuelve:
{ "access_token": "...", "token_type": "Bearer", "expires_in": 43200, "refresh_token": "...", "scope": "..." }
- Cuerpo:
-
Renovar el token:
POST /membership/oauth/token(Pública)- Cuerpo:
{ "grant_type": "refresh_token", "refresh_token": "...", "client_id": "...", "client_secret": "..." }
- Cuerpo:
Los tokens de acceso caducan a las 12 horas.
Flujo de código de dispositivo (RFC 8628)
Para dispositivos sin navegador (aplicaciones de televisión, quioscos):
-
Solicitar un código de dispositivo:
POST /membership/oauth/device/authorize(Pública)- Cuerpo:
{ "client_id": "...", "scope": "..." } - Devuelve:
{ "device_code": "...", "user_code": "ABCD-1234", "verification_uri": "https://app.b1.church/device", "expires_in": 900, "interval": 5 }
- Cuerpo:
-
El usuario ingresa el código en la URI de verificación y aprueba o niega el acceso
-
Sondear para obtener el token:
POST /membership/oauth/token(Pública)- Cuerpo:
{ "grant_type": "urn:ietf:params:oauth:grant-type:device_code", "device_code": "...", "client_id": "..." } - Devuelve
authorization_pendinghasta que se apruebe, y luego devuelve el token de acceso
- Cuerpo:
Administración de clientes OAuth
| Método | Ruta | Autenticación | Permiso | Descripción |
|---|---|---|---|---|
| GET | /membership/oauth/clients | JWT | Server.Admin | Enumera todos los clientes OAuth |
| GET | /membership/oauth/clients/:id | JWT | Server.Admin | Obtiene un cliente por ID |
| GET | /membership/oauth/clients/clientId/:clientId | JWT | — | Obtiene un cliente por su client ID (secreto oculto) |
| POST | /membership/oauth/clients | JWT | Server.Admin | Crea o actualiza un cliente |
| DELETE | /membership/oauth/clients/:id | JWT | Server.Admin | Elimina un cliente |
| POST | /membership/oauth/register | Pública | — | Registro dinámico de clientes (RFC 7591) para clientes públicos como los conectores MCP. Consulte Aplicaciones conectadas |
Endpoints de aprobación de dispositivos
| Método | Ruta | Autenticación | Descripción |
|---|---|---|---|
| GET | /membership/oauth/device/pending/:userCode | JWT | Obtiene la información del código de dispositivo pendiente para la interfaz de aprobación |
| POST | /membership/oauth/device/approve | JWT | Aprueba una autorización de dispositivo. Cuerpo: { "user_code": "...", "church_id": "..." } |
| POST | /membership/oauth/device/deny | JWT | Niega una autorización de dispositivo. Cuerpo: { "user_code": "..." } |
Endpoints públicos y autenticados
La API usa dos funciones envolventes que determinan los requisitos de autenticación:
actionWrapper: exige un JWT válido. El objeto de usuario autenticado (au) está disponible conchurchId,userIdy las verificaciones de permisos.actionWrapperAnon: no exige autenticación. Se usa para inicio de sesión, registro, consultas de contenido público y receptores de webhooks.
En las tablas de endpoints de esta documentación, estas se indican como JWT y Pública, respectivamente, en la columna Autenticación.
Páginas relacionadas
- Estructura de módulos: cómo se organizan los controladores, repositorios y modelos
- Configuración local: ejecutar la API localmente para desarrollo