Autenticación

Toda llamada a la API REST requiere dos cabeceras:


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

tenant-key es el slug de la iglesia (ej. la-roca). Sin esa cabecera la API responde 400 Bad Request: Missing X-Tenant.

Tipos de token

Tipo	Caso	Vigencia
Personal Access Token (PAT)	Scripts personales, Postman	90 días
Service Token	Backends, integraciones de larga duración	1 año
OAuth Access Token	Apps de terceros (Zapier, partners)	1 hora (con refresh)
API Key del kiosko	Solo para el dispositivo, scope minimal	Permanente, rotable

Crear un PAT

Configuración → Mi cuenta → Tokens → Nuevo.
Nombre descriptivo (“Postman local”).
Selecciona scopes (lista abajo).
Crear → copia el token (sólo se muestra una vez).


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

Crear un Service Token

Configuración → Iglesia → Service Tokens → Nuevo. Sólo org_admin puede crearlos. El service token no está atado a un usuario humano — sobrevive a la salida del staff que lo creó.

Trate los tokens como contraseñas

Cualquiera con el token actúa como su iglesia. Nunca los meta en código en repositorios públicos. Use variables de entorno o un secret manager (1Password, Vault).

Scopes

Los scopes limitan qué puede hacer el token. Granularidad por recurso × acción:


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:*               (todo, sólo para org_admin)

Si pide un scope que no tiene en su rol, la creación del token falla.

Rotación

PATs caducan a 90 días. Service tokens a 1 año. 2 semanas antes del vencimiento, Ministrium notifica al dueño por email + push. Para rotar:

Generar nuevo token.
Actualizar en su sistema.
Revocar el antiguo (Configuración → Tokens → Revocar).

Si un token se revoca, las llamadas siguientes responden 401 Unauthorized: Token revoked instantáneamente.

Compromiso

Si sospecha que un token fue expuesto:

Revoque inmediatamente desde la UI o vía DELETE /v1/auth/tokens/<id>.
Revise el log de auditoría: cualquier acción del token aparece con su nombre.
Genere un nuevo token con scopes mínimos necesarios.

OAuth (apps de terceros)

Para apps que actúan en nombre de un usuario (Zapier, partners), Ministrium expone 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>

Flujo PKCE estándar. Refresh tokens válidos 30 días.

OpenAPI spec

Disponible en /v1/openapi.json (público) y /v1/openapi.yaml. Compatible con Swagger UI, Postman, Insomnia.