Saltar al contenido principal

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:

CampoDescripción
email + passwordInicio de sesión estándar con correo electrónico y contraseña
jwtVolver a autenticarse con un JWT existente
authGuidEnlace 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):

EndpointDescripción
GET /status{ enabled, backupCodesLeft }
POST /setupInicia la configuración; devuelve { secret, otpauthUrl } para el código QR
POST /enableCuerpo { code }; la activa y devuelve { backupCodes } una sola vez
POST /disableCuerpo { code } (código de la aplicación o de respaldo); la desactiva
POST /reset/:userIdSolo 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 usuario
  • churchId: iglesia seleccionada actualmente
  • personId: 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étodoRutaAutenticaciónDescripción
POST/membership/users/forgotPúblicaEnvía un correo de restablecimiento de contraseña. Cuerpo: { "userEmail": "...", "appName": "...", "appUrl": "..." }
POST/membership/users/setPasswordGuidPúblicaEstablece una nueva contraseña con un GUID de autenticación del correo de restablecimiento. Cuerpo: { "authGuid": "...", "newPassword": "..." }
POST/membership/users/updatePasswordJWTCambia 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 visibleTipo de contenidoAcciónDescripción
AttendanceAttendanceCheckinRegistrar la entrada de miembros en los servicios
AttendanceEditEditar registros de asistencia
ServicesEditAdministrar servicios y horarios de servicio
AttendanceViewVer registros de asistencia
AttendanceView SummaryVer resúmenes e informes de asistencia
DonationsDonationsEditCrear y editar registros de donaciones
SettingsEditEditar la configuración de ofrendas y pagos
DonationsView SummaryVer informes resumidos de donaciones
DonationsViewVer registros individuales de donaciones
People and GroupsFormsAdminAdministración completa de formularios
FormsEditEditar definiciones de formularios
PlansEditEditar planes de servicio
Group MembersEditAgregar o quitar miembros de grupos
GroupsEditCrear y editar grupos
HouseholdsEditEditar las asignaciones de hogares
PeopleEditEditar cualquier registro de persona
PeopleEdit SelfEditar solo su propio registro de persona
RolesEditAdministrar roles y asignaciones de usuarios
Group MembersViewVer listas de miembros de grupos
PeopleView MembersVer solo miembros (no visitantes)
PeopleViewVer todas las personas
RolesViewVer roles y asignaciones
SettingsEditEditar la configuración de la iglesia
ContentContentEditEditar páginas, secciones y elementos
SettingsEditEditar la configuración de contenido
StreamingServicesEditAdministrar la configuración de los servicios de transmisión
ChatHostOrganizar y moderar sesiones de chat
MessagingTextingSendEnviar 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​

  1. 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, solo S256) son obligatorios para clientes públicos sin secreto
    • Devuelve: { "code": "...", "state": "..." }
  2. 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_verifier cuando el paso de autorización usó un code_challenge; los clientes públicos omiten client_secret. Se aceptan cuerpos JSON o codificados como formulario
    • Devuelve: { "access_token": "...", "token_type": "Bearer", "expires_in": 43200, "refresh_token": "...", "scope": "..." }
  3. Renovar el token: POST /membership/oauth/token (Pública)

    • Cuerpo: { "grant_type": "refresh_token", "refresh_token": "...", "client_id": "...", "client_secret": "..." }

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):

  1. 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 }
  2. El usuario ingresa el código en la URI de verificación y aprueba o niega el acceso

  3. 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_pending hasta que se apruebe, y luego devuelve el token de acceso

Administración de clientes OAuth​

MétodoRutaAutenticaciónPermisoDescripción
GET/membership/oauth/clientsJWTServer.AdminEnumera todos los clientes OAuth
GET/membership/oauth/clients/:idJWTServer.AdminObtiene un cliente por ID
GET/membership/oauth/clients/clientId/:clientIdJWT—Obtiene un cliente por su client ID (secreto oculto)
POST/membership/oauth/clientsJWTServer.AdminCrea o actualiza un cliente
DELETE/membership/oauth/clients/:idJWTServer.AdminElimina un cliente
POST/membership/oauth/registerPú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étodoRutaAutenticaciónDescripción
GET/membership/oauth/device/pending/:userCodeJWTObtiene la información del código de dispositivo pendiente para la interfaz de aprobación
POST/membership/oauth/device/approveJWTAprueba una autorización de dispositivo. Cuerpo: { "user_code": "...", "church_id": "..." }
POST/membership/oauth/device/denyJWTNiega 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 con churchId, userId y 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​