Authentication

Every call to the REST API requires two headers:


Authorization: Bearer <token>
X-Tenant: <tenant-key>

tenant-key is the church slug (e.g. la-roca). Without that header the API replies 400 Bad Request: Missing X-Tenant.

Token types

Type	Case	Lifetime
Personal Access Token (PAT)	Personal scripts, Postman	90 days
Service Token	Backends, long-running integrations	1 year
OAuth Access Token	Third-party apps (Zapier, partners)	1 hour (with refresh)
Kiosk API Key	Device only, minimal scope	Permanent, rotatable

Create a PAT

Settings → My account → Tokens → New.
Descriptive name (“Postman local”).
Pick scopes (list below).
Create → copy the token (shown only once).


curl https://api.ministrium.com/v1/members/mem_123 \
  -H "Authorization: Bearer ms_pat_AbCdEf123..." \
  -H "X-Tenant: la-roca"

Create a Service Token

Settings → Church → Service Tokens → New. Only org_admin can create them. The service token isn’t tied to a human user — it survives the staffer who created it leaving.

Treat tokens like passwords

Anyone with the token acts as your church. Never commit them to public repos. Use environment variables or a secret manager (1Password, Vault).

Scopes

Scopes limit what the token can do. Granularity per resource × action:


read:members          write:members
read:donations        write:donations
read:attendance       write:attendance
read:events           write:events
read:groups           write:groups
read:reports          (no write)
read:campuses         write:campuses
admin:*               (everything, org_admin only)

If you request a scope your role doesn’t have, token creation fails.

Rotation

PATs expire at 90 days. Service tokens at 1 year. 2 weeks before expiry, Ministrium notifies the owner via email + push. To rotate:

Generate the new token.
Update in your system.
Revoke the old (Settings → Tokens → Revoke).

If a token is revoked, subsequent calls reply 401 Unauthorized: Token revoked instantly.

Compromise

If you suspect a token was leaked:

Revoke immediately from the UI or via DELETE /v1/auth/tokens/<id>.
Review the audit log: every action by the token appears with its name.
Generate a new token with the minimum required scopes.

OAuth (third-party apps)

For apps acting on behalf of a user (Zapier, partners), Ministrium exposes OAuth 2.0:


GET /v1/oauth/authorize?
  client_id=app_xyz&
  redirect_uri=https://app.partner.com/cb&
  scope=read:members+write:donations&
  state=<csrf>

Standard PKCE flow. Refresh tokens valid 30 days.

OpenAPI spec

Available at /v1/openapi.json (public) and /v1/openapi.yaml. Compatible with Swagger UI, Postman, Insomnia.