Church users and roles
The people who sign in to the portal for a church: admins who can do everything, and users who can do exactly what their permission list allows.
A church has two roles. An admin holds every church:* permission. A user holds the list chosen when they are invited or edited, drawn from GET /v1/users/permissions. New users get an email invitation to choose a password; until they do, invited is true.
Users
| Route | Permission | Purpose |
|---|---|---|
| GET/v1/users | church:users:view | The church's users (q, status, page, page_size). |
| GET/v1/users/permissions | church:users:view | Every church permission a user can be given, with its description. |
| POST/v1/users | church:users:create | Invite a user. |
| GET/v1/users/{uuid} | church:users:view | One user with their permissions. |
| PUT/v1/users/{uuid} | church:users:edit | Change name, phone, role or permissions. |
| POST/v1/users/{uuid}/status | church:users:edit | Activate or deactivate (status: active | inactive). You cannot change your own status. |
| POST/v1/users/{uuid}/resend-invitation | church:users:edit | Send the invitation email again, for a user who has not chosen a password yet. |
Read routes also accept head_office:churches:view and system:churches:view with an X-Church header.
User fields
| Field | Type | Required | Description |
|---|---|---|---|
| first_name | string | Yes | First name. |
| other_names | string | No | Other names. |
| string | Yes | Sign-in email, unique across the platform (409 if taken). | |
| phone | string | No | Phone number. |
| role | string | Yes | admin or user. |
| permissions | string[] | No | church:* permission names, for role user only. |
# Paste your token once (it starts with mc_):
export MYCHURCH_TOKEN="mc_your_token_here"
curl -X POST https://uat-api.mychurch.co.ke/v1/users \
-H "Authorization: Bearer $MYCHURCH_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"first_name": "Peter",
"other_names": "Otieno",
"email": "[email protected]",
"phone": "0722000111",
"role": "user",
"permissions": [
"church:members:view",
"church:collections:view",
"church:transactions:view",
"church:reports:generate"
]
}'{
"success": true,
"data": {
"uuid": "6f0d2a8e-0000-4000-8000-00000000a002",
"scope": "church",
"first_name": "Peter",
"other_names": "Otieno",
"name": "Peter Otieno",
"email": "[email protected]",
"phone": "254722000111",
"role": "user",
"status": "active",
"invited": true,
"invited_at": "2026-11-01T10:05:00Z",
"church_uuid": "11111111-2222-4333-8444-555555555555",
"church_name": "Example Fellowship Church",
"permissions": ["church:members:view", "church:collections:view", "church:transactions:view", "church:reports:generate"]
}
}Changes take effect quickly
Permission names
Permission strings read church:<resource>:<action>. The reference pages list the one each route checks, for example members (church:members:view|create|edit|delete|approve|import|export), giving (church:collections:view|manage|reconcile, church:transactions:view|export, church:paybills:manage) and finance (church:expenses:*, church:budgets:*, church:requisitions:create|edit|approve|pay). An mc_ token is limited to its own list in the same way as a user.
Head office and staff accounts
Head office users and Bitwise staff are managed by MyChurch under /v1/system/users and /v1/system/rbac, which need system:* permissions and are not open to church credentials. A head office manages its own users under /v1/head-office/users with head_office:users:manage.