Hopp til hovedinnhold

Autentisering og tillatelser

ChurchApps API bruker JWT-basert autentisering. Brukere logger inn for å motta et token som koder identiteten deres, kirketilhørigheten og tillatelsene deres. Denne siden dekker autentiseringsflyten, tillatelsesmodellen og OAuth-støtten.

Innloggingsflyt​

Standard innlogging​

POST /membership/users/login

Autentisering: Offentlig

Godtar en av tre typer legitimasjon:

FeltBeskrivelse
email + passwordStandard innlogging med e-post og passord
jwtAutentiser på nytt med et eksisterende JWT
authGuidEngangs-autentiseringslenke (brukt i velkomst- og tilbakestillings-e-poster)

Respons:

{
"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>"
}

Feltet token er et JWT som skal sendes som Authorization: Bearer <token> i påfølgende forespørsler.

Tofaktorinnlogging​

Brukere kan slå på tofaktorinnlogging med autentiseringsapp (TOTP). For disse brukerne returnerer en email + password-, authGuid- eller SSO-innlogging ikke et token. I stedet svarer den med en utfordring:

{ "mfaRequired": true, "mfaToken": "<challenge-token>" }

Utfordringstokenet gjelder i 5 minutter. Send det tilbake til samme endepunkt sammen med koden:

{ "mfaToken": "<challenge-token>", "mfaCode": "123456" }

mfaCode kan være den nåværende 6-sifrede koden fra autentiseringsappen, eller en av brukerens ti engangs-reservekoder. En feil kode returnerer Invalid code, og gjentatte feil begrenses per konto. En innlogging med jwt utfordres aldri, slik at eksisterende økter fortsetter å fornyes. Innloggingsresponsens user-objekt har feltet mfaEnabled.

Selvbetjeningsendepunkter (kun for innlogget bruker, under /membership/users/mfa):

EndepunktBeskrivelse
GET /status{ enabled, backupCodesLeft }
POST /setupStarter oppsettet; returnerer { secret, otpauthUrl } for QR-koden
POST /enableBody { code }; slår den på og returnerer { backupCodes } én gang
POST /disableBody { code } (autentiserings- eller reservekode); slår den av
POST /reset/:userIdKun Server.Admin; slår den av for en annen bruker

Hemmeligheter lagres kryptert, og reservekoder lagres som hasher. Aktivering, deaktivering og tilbakestilling skrives til revisjonsloggen.

Tokeninnhold​

JWT koder:

  • id — Bruker-ID
  • churchId — Valgt kirke
  • personId — Personpost for den valgte kirken
  • Tillatelsesmatriser per API

Kirkevalg​

Brukere kan tilhøre flere kirker. Innloggingsresponsen inkluderer alle kirker med deres tillatelser. For å bytte kirke genererer klienten et nytt JWT avgrenset til en annen kirke, basert på dataene i innloggingsresponsen.

Brukerregistrering​

Registrer en ny bruker​

POST /membership/users/register

Autentisering: Offentlig

{
"email": "jane@example.com",
"firstName": "Jane",
"lastName": "Doe",
"appName": "B1 Admin",
"appUrl": "https://app.b1.church"
}

Oppretter en bruker med et midlertidig passord og sender en velkomst-e-post med en autentiseringslenke. Den første brukeren som registreres på en ny instans, får automatisk tilgang som serveradministrator.

To valgfrie felt for bottfelle godtas: website (et skjult honeypot-felt som ekte brukere lar stå tomt) og fillMs (hvor lenge skjemaet var åpent, i millisekunder). Hvis website er fylt ut eller fillMs er under 2000, opprettes ingen konto, men endepunktet returnerer likevel en vanlig 200-respons, slik at bots ikke kan se at de ble avvist. Klienter som utelater begge feltene registrerer seg som vanlig.

Registrer en ny kirke​

POST /membership/churches/add

Autentisering: JWT

Etter at du har registrert en bruker, kall dette endepunktet for å opprette en kirke og knytte brukeren til den.

Passordhåndtering​

MetodeStiAutentiseringBeskrivelse
POST/membership/users/forgotOffentligSend en e-post for tilbakestilling av passord. Body: { "userEmail": "...", "appName": "...", "appUrl": "..." }
POST/membership/users/setPasswordGuidOffentligSett et nytt passord ved hjelp av en auth-GUID fra en tilbakestillings-e-post. Body: { "authGuid": "...", "newPassword": "..." }
POST/membership/users/updatePasswordJWTEndre den innloggede brukerens passord. Body: { "newPassword": "..." }

Tillatelsesmodell​

Tillatelser er organisert etter modul og tilordnes brukere gjennom roller. Hver tillatelse har en innholdstype og en handling.

Tillatelsesreferanse​

VisningsseksjonInnholdstypeHandlingBeskrivelse
OppmøteAttendanceCheckinSjekk inn medlemmer ved gudstjenester
AttendanceEditRediger oppmøteregistreringer
ServicesEditAdministrer gudstjenester og gudstjenestetider
AttendanceViewSe oppmøteregistreringer
AttendanceView SummarySe oppmøteoppsummeringer og rapporter
GaverDonationsEditOpprett og rediger giveregistreringer
SettingsEditRediger innstillinger for gaver/betaling
DonationsView SummarySe oppsummeringsrapporter for gaver
DonationsViewSe enkeltregistreringer av gaver
Personer og grupperFormsAdminFull administrasjon av skjemaer
FormsEditRediger skjemadefinisjoner
PlansEditRediger tjenesteplaner
Group MembersEditLegg til/fjern gruppemedlemmer
GroupsEditOpprett og rediger grupper
HouseholdsEditRediger husstandstilordninger
PeopleEditRediger alle personposter
PeopleEdit SelfRediger bare din egen personpost
RolesEditAdministrer roller og brukertilordninger
Group MembersViewSe gruppemedlemslister
PeopleView MembersSe bare medlemmer (ikke besøkende)
PeopleViewSe alle personer
RolesViewSe roller og tilordninger
SettingsEditRediger kirkeinnstillinger
InnholdContentEditRediger sider, seksjoner, elementer
SettingsEditRediger innholdsinnstillinger
StreamingServicesEditAdministrer konfigurasjon av direktesending
ChatHostVær vert for/moderer chatøkter
MeldingerTextingSendSend SMS-meldinger

Slik sjekkes tillatelser​

I kontrollere sjekkes tillatelser med metoden au.checkAccess():

// Krev en bestemt tillatelse
if (!au.checkAccess(Permissions.people.edit)) return this.json({}, 401);

// Eller innenfor actionWrapper — CRUD-systemet sjekker automatisk
crudSettings: {
permissions: {
view: Permissions.people.view,
edit: Permissions.people.edit
}
}

Serveradministrator​

Tillatelsen Server.Admin gir full tilgang på tvers av alle kirker. Den tilordnes den første registrerte brukeren og kan gis til andre gjennom serveradministratorrollen.

OAuth 2.0​

API-et støtter OAuth 2.0 for tredjepartsintegrasjoner. To granttyper er tilgjengelige.

Autorisasjonskodeflyt​

  1. Autoriser: POST /membership/oauth/authorize (krever JWT)

    • Body: { "client_id": "...", "redirect_uri": "...", "response_type": "code", "scope": "...", "state": "...", "code_challenge": "...", "code_challenge_method": "S256" }
    • code_challenge / code_challenge_method (PKCE, kun S256) kreves for offentlige klienter uten hemmelighet
    • Returnerer: { "code": "...", "state": "..." }
  2. Bytt kode mot token: POST /membership/oauth/token (Offentlig)

    • Body: { "grant_type": "authorization_code", "code": "...", "client_id": "...", "client_secret": "...", "redirect_uri": "...", "code_verifier": "..." }
    • Send code_verifier når autoriseringssteget brukte en code_challenge; offentlige klienter utelater client_secret. JSON- og skjemakodede body-formater godtas
    • Returnerer: { "access_token": "...", "token_type": "Bearer", "expires_in": 43200, "refresh_token": "...", "scope": "..." }
  3. Forny token: POST /membership/oauth/token (Offentlig)

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

Tilgangstokener utløper etter 12 timer.

Enhetskodeflyt (RFC 8628)​

For enheter uten nettleser (TV-apper, kiosker):

  1. Be om enhetskode: POST /membership/oauth/device/authorize (Offentlig)

    • Body: { "client_id": "...", "scope": "..." }
    • Returnerer: { "device_code": "...", "user_code": "ABCD-1234", "verification_uri": "https://app.b1.church/device", "expires_in": 900, "interval": 5 }
  2. Brukeren skriver inn koden på verifiseringsadressen og godkjenner eller avslår

  3. Spør etter token: POST /membership/oauth/token (Offentlig)

    • Body: { "grant_type": "urn:ietf:params:oauth:grant-type:device_code", "device_code": "...", "client_id": "..." }
    • Returnerer authorization_pending til den er godkjent, og returnerer deretter tilgangstokenet

Administrasjon av OAuth-klienter​

MetodeStiAutentiseringTillatelseBeskrivelse
GET/membership/oauth/clientsJWTServer.AdminList alle OAuth-klienter
GET/membership/oauth/clients/:idJWTServer.AdminHent klient etter ID
GET/membership/oauth/clients/clientId/:clientIdJWT—Hent klient etter klient-ID (hemmelighet skjult)
POST/membership/oauth/clientsJWTServer.AdminOpprett eller oppdater en klient
DELETE/membership/oauth/clients/:idJWTServer.AdminSlett en klient
POST/membership/oauth/registerOffentlig—Dynamisk klientregistrering (RFC 7591) for offentlige klienter som MCP-tilkoblinger. Se Tilkoblede apper

Endepunkter for godkjenning av enheter​

MetodeStiAutentiseringBeskrivelse
GET/membership/oauth/device/pending/:userCodeJWTHent info om ventende enhetskode for godkjenningsgrensesnittet
POST/membership/oauth/device/approveJWTGodkjenn en enhetsautorisasjon. Body: { "user_code": "...", "church_id": "..." }
POST/membership/oauth/device/denyJWTAvslå en enhetsautorisasjon. Body: { "user_code": "..." }

Offentlige vs. autentiserte endepunkter​

API-et bruker to innpakningsfunksjoner som avgjør autentiseringskrav:

  • actionWrapper — Krever et gyldig JWT. Den autentiserte brukerobjektet (au) er tilgjengelig med churchId, userId og tillatelsessjekker.
  • actionWrapperAnon — Ingen autentisering kreves. Brukes til innlogging, registrering, offentlige innholdsoppslag og webhook-mottakere.

I endepunkttabellene i denne dokumentasjonen angis disse som henholdsvis JWT og Offentlig i kolonnen Autentisering.

Relaterte sider​