Authentication

Every authenticated call sends one header: Authorization: Bearer <token>. What the token is depends on who is calling.

Caller	Routes	Token
Member (mobile app)	`/api/v2/`, `/api/v1/`	Member token: a uuid issued at login
Church user (admin or staff)	`/v1/*`	JWT from `/auth/login`, scope `church`
Head office user	`/v1/`, `/v1/head-office/`	JWT, scope `head_office`
MyChurch staff	`/v1/`, `/v1/system/`	JWT, scope `system`
An integration acting for one church	`/v1/*`	Scoped API token starting `mc_`

Member tokens (member app API)

POST /api/v2/login/{church} (or the OTP login, verify-otp/{church}) returns a token, a uuid. The app stores it and sends it on every member route:

bash

curl https://uat-api.mychurch.co.ke/api/v2/profile \
  -H "Authorization: Bearer 00000000-0000-4000-8000-00000000f00d"

A member has one live token. Logging in again replaces it; POST /api/v2/logout ends it.
A missing or unknown token answers HTTP 401 with {"message": "Unauthenticated", "status": false}. It is the only member-route failure that is not HTTP 200. The app treats it as "go back to login".
Routes with {church} in the path and a member token (check-in, trustees, OTP login, change forgot PIN) require the member to belong to that church. A token from another church answers 401.
The same routes also accept a member JWT (scope member), which is what new app versions will use on the member routes of the platform API once they ship.

PIN encryption in the shipped apps

The installed MyChurch apps encrypt the member's four-digit PIN with AES-256-CBC, using a key built into the app, before sending it in the pin field of login, registration and the PIN-guarded routes (delete a child, invite or remove a spouse, register a child, request data deletion, child trustees). The API decrypts it and checks it against the stored bcrypt hash. This is legacy app behaviour kept so installed apps keep working: the key is not published, and the first app release on the platform API sends the PIN as typed, over TLS only, with no app-side encryption.

The church list access key

GET /api/v2/churches and GET /api/v2/all-churches require a CHURCHES-ACCESS-KEY header that the shipped apps send on every request. Without the right value they answer HTTP 401 {"message": "Unauthorized", "status": false}. The value is issued to the app team and is not published; other integrations should read churches through the platform API instead. It will be retired by the same app release.

Platform JWTs (portal users)

Church users, head office users and MyChurch staff sign in with email and password; a six-digit code is emailed as the second step. The result is a signed JWT (HS256) carrying the user uuid, the scope, the role, the church or head office uuid and, for the user role only, the list of permissions. Details and examples are in Platform API: Login and sessions.

Sessions expire after 60 minutes without use by default; POST /auth/refresh extends a live one.
Logging out, changing a password or an administrator deactivating the user revokes existing tokens on the next request.
Repeated wrong passwords lock the account for a while; OTP sends are rate limited per email.

Scopes, roles and permissions

Every /v1 route needs one permission string of the form scope:resource:action, for example church:members:view. A church admin holds every church:* permission; a church user holds the ones the admin granted. Staff with the super_admin role hold everything. Head office and staff users act on one church at a time by sending X-Church: <church uuid>; read routes accept head_office:churches:view and system:churches:view so they can look at a church's data without being one of its users.

mc_ API tokens (integrations)

An mc_ token belongs to one church and carries an explicit list of church:* permissions, never the admin role. Use it for a server-to-server integration (an accounting system reading the collection ledger, a website listing sermons) so no person's password is involved.

bash

export MYCHURCH_TOKEN="mc_your_token_here"

curl "https://uat-api.mychurch.co.ke/v1/collection-transactions?from=2026-10-01&to=2026-10-31" \
  -H "Authorization: Bearer $MYCHURCH_TOKEN"

Only a SHA-256 hash of the token is stored. Copy it when it is issued; it cannot be shown again.
Tokens can carry an expiry date and can be revoked at any time; a revoked token stops working within 30 seconds.
A token of a church that is suspended, or still on the previous MyChurch system, does not authenticate.

Getting a token

Tokens are issued by MyChurch support for now: write to [email protected] from a church administrator's address with the integration's name and the permissions it needs. Self-service tokens in the portal are on the way and will be announced in the changelog.

Keep tokens safe

Never put a token, a member token or a PIN in a URL, a log line or a support ticket.
Call the API from your server, never from a web page where the token would be visible.
Give an mc_ token the fewest permissions that do the job, and one token per integration so each can be revoked alone.