API Tokens

Personal API tokens let you (or your scripts and integrations) authenticate to the ChurchCRM API without using your password. Each token acts as a long-lived credential scoped to your user account.

---

Generating a Token

1. Open the user menu (your name, top right) and click Change Settings
2. Open API Access
3. Copy the API Key shown in the field. There is no separate token list.

Regenerate replaces that key. The previous key stops working. Store the new value somewhere safe (for example, a password manager).

Treat tokens like passwords

Anyone with your token can authenticate to the API as you. Do not commit tokens to source control or paste them in chat messages.

---

Using a Token

Pass the token in the x-api-key header on every API request:

GET /api/persons/latest HTTP/1.1
Host: your-church.example.com
x-api-key: YOUR_TOKEN_HERE

Or with curl:

curl -H "x-api-key: YOUR_TOKEN_HERE" \
     https://your-church.example.com/api/persons/latest

Use x-api-key, not Authorization: Bearer

ChurchCRM reads the token from the x-api-key header only. An Authorization: Bearer … header is ignored, and the request fails with 401 {"error":"No logged in user"}.

Tokens are stateless — each request is authenticated independently. There is no session to refresh and no token-expiry handshake.

Base URL

ChurchCRM is self-hosted, and the API lives under the install root. If ChurchCRM is installed in a subdirectory, include it:

https://your-church.example.com/api/persons/latest        # root install
https://your-church.example.com/crm/api/persons/latest    # installed in /crm

To confirm you have the right base URL before authenticating, call the unauthenticated health check — it needs no token:

curl https://your-church.example.com/api/public/echo
# {"message":"echo"}

Getting a token programmatically

Instead of generating a token in the UI, you can exchange a username and password for one:

curl -X POST https://your-church.example.com/api/public/user/login \
     -H "Content-Type: application/json" \
     -d '{"userName":"admin","password":"secret"}'
# {"apiKey":"YOUR_TOKEN_HERE"}

If the account has two-factor authentication enabled, this returns 202 {"requiresOTP":true} instead. Repeat the request with an otp field containing a TOTP code or a recovery code:

     -d '{"userName":"admin","password":"secret","otp":"123456"}'

---

Token Scopes

Tokens inherit the permissions of the user account that created them. A token created by an Admin account has Admin-level access; a token from a view-only account has view-only access.

There is currently no way to create a token with reduced permissions relative to your account.

Individual endpoints are gated by role (Finance, Admin, EditRecords, DeleteRecords, ManageGroups, AddEvents, MenuOptions). Calling one your account lacks returns 403, so a client should treat a 403 as "this feature is unavailable to this user" rather than an error. Retrying will not help — tokens are static.

---

Replacing a key

1. Open Change Settings → API Access
2. Click Regenerate

The old key stops working immediately. Update any scripts that used it. There is no token list and no separate revoke button.

---

API Reference

• Public API — Requires no authentication: login, password reset, self-registration, public calendar feeds, and country/state lookups
• Private API — Requires a token via x-api-key. Available to any authenticated user; individual endpoints are further restricted by role