Skip to content
FolioSign inStart your trial

Docs · Partners and devices

Partners

Create customer churches, act for them with one key, mint church keys, and receive their events.

A partner church (on the Partner plan, with the partners feature granted) creates and runs customer churches through the API. Building a product for many churches is the main use.

Two ways to work with a customer church#

  1. Act for it with your partner key. Send X-Folio-Church: <church id or slug> on any church route and the call runs as that church: teachings, uploads, notes, outputs, Ask, scripture, webhooks, usage and billing reads. Plan checks run against the customer, so usage is metered to them.
  2. Mint a church key for it and give that key to the church's own system.

Partner keys#

Create a partner key in the console (Developers, Partners). It needs a recent sign-in. Scopes:

ScopeMeaning
*Everything, including partner routes.
machine:*Every church scope, but not partner routes.
machine:readEvery read scope.
partners:read, partners:writeList and create customer churches, issue and revoke their keys.

A partner key can also carry church_ids to limit which customer churches it may act for, an ip_allowlist, and rate_limit_per_minute.

Create a customer church#

curl -X POST "$FOLIO_API_URL/v1/partner/churches" \
  -H "Authorization: Bearer $FOLIO_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: customer-grace-chapel" \
  -d '{
  "name": "Grace Chapel",
  "slug": "grace-chapel",
  "admin_email": "[email protected]"
}'
Response
{
  "status": true,
  "message": "partner_church",
  "data": { "id": "sac_0192f7a8-3b1c-7d2e-9a40-5c6d7e8f9012", "object": "church", "church_id": "org_0192f7a8-3b1c-7d2e-9a40-5c6d7e8f9012", "name": "Grace Chapel", "slug": "grace-chapel", "admin_email": "[email protected]", "sandbox": false, "expires_at": null }
}

The admin is invited at admin_email. church_id is what you send as X-Folio-Church. Creating a live church counts against your churches meter. List what you run with GET /v1/partner/churches.

Act as a customer church#

curl -X GET "$FOLIO_API_URL/v1/teachings" \
  -H "Authorization: Bearer $FOLIO_API_KEY" \
  -H "X-Folio-Church: org_0192f7a8-3b1c-7d2e-9a40-5c6d7e8f9012"

What the header does and does not allow:

  • The target must be one of your own customer churches. The link is read from the database on every call. Another partner's church, an unrelated church, an unknown id and a deleted church all answer 404 the same way.
  • A suspended church answers 403. A key limited to other churches answers 403.
  • Test keys cannot use the header. Sandbox churches take only their own folio_test_ keys.
  • The header is refused (400) on /v1/partner/… routes.
  • Every call made this way is recorded in the audit trail of both the customer church and your partner church, with the key id, method, path and request id.

Issue a key for a customer church#

curl -X POST "$FOLIO_API_URL/v1/partner/churches/org_0192f7a8-3b1c-7d2e-9a40-5c6d7e8f9012/keys" \
  -H "Authorization: Bearer $FOLIO_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "CRM sync",
  "scopes": [
    "teachings:read",
    "notes:read"
  ]
}'

The response holds the full key once. A church key can carry only scopes your programme grants. Revoke it with DELETE /v1/partner/churches/{church}/keys/{key}.

Usage, thresholds and billing#

Read a customer's plan and usage by acting as them:

curl -X GET "$FOLIO_API_URL/v1/billing" \
  -H "Authorization: Bearer $FOLIO_API_KEY" \
  -H "X-Folio-Church: org_0192f7a8-3b1c-7d2e-9a40-5c6d7e8f9012"

Instead of polling, subscribe a partner endpoint to partner.church.usage_threshold. It is sent once per billing period when a church's use of a plan allowance first reaches 80 percent, and again at 100 percent. Other partner events cover partner.church.created, .updated, .suspended, .deleted, .plan_changed and partner.key.issued; see the catalogue. Plan prices change, so read them from GET /v1/public/plans rather than copying numbers.

Partner webhooks#

One endpoint can receive every customer church's events: set child_scope to all, or to selected with church_ids. partner.church.deleted is sent twice for a church: with stage of scheduled when deletion is requested, and purged once the data is removed (the purged event carries only the church's id, slug and name). See webhooks.

Limits#

Rate limits are the partner's shared bucket across all its keys and children, a per-customer bucket so one church cannot use up the rest, and the key's own limit. Sandbox churches are covered in sandbox and testing.

Verified against API version 0.0.0-dev. Generated from the live OpenAPI document.