Docs · Concepts
Authentication and scopes
The three kinds of key, how scopes and wildcards work, sandbox keys, rotation and least privilege.
Send every authenticated call as Authorization: Bearer <key>. Which key an operation takes, and the scope it needs, are on each operation in the API reference and in the OpenAPI document under security and x-required-scopes.
Key types#
| Key | Looks like | Use it for |
|---|---|---|
| Church key | folio_live_… or folio_test_… | Server-to-server calls for one church. Created in the console under Developers. |
| Partner key | folio_live_… created in a partner church | Create and run customer churches, and call any church route as one of them with X-Folio-Church. See partners. |
| Device key | folio_booth_… | A booth machine running Folio Live. Returned once when a booth is paired. See booth devices. |
A few routes need no key: published content, the widget, public Ask, subscribe, live captions, the plan catalogue and the event catalogue. They are marked No key in the reference.
Live and test keys#
folio_live_ keys work against real churches only. folio_test_ keys work against sandbox churches only. The check runs on every request, so a test key can never reach a live church and a live key can never reach a sandbox church. See sandbox and testing.
Scopes#
A scope names one capability, such as notes:read or webhooks:write. A call needs the scope listed on its operation; without it the answer is 403 permission_denied.
| Wildcard | Grants |
|---|---|
machine:read | Every read scope. Nothing that creates or changes. |
machine:* | Every church scope. |
* | Everything, including partner routes. Partner keys only. |
When you create a key in the console the presets are Full access, Read only and Custom. Prefer Custom: give a key only the scopes its job needs, and use one key per integration so you can revoke one without touching the others.
Scopes cannot be changed after a key is created. To change them, create a new key and retire the old one.
What else a key can carry#
| Setting | Effect |
|---|---|
expires_at | After this time the key answers 401. The service enforces a maximum lifetime. |
ip_allowlist | Up to 20 addresses or ranges. A request from anywhere else answers 403. |
rate_limit_per_minute | A lower limit for this key. See rate limits. |
church_ids | Partner keys only: act only for these customer churches. |
Creating and rotating keys#
Creating a key needs a recent sign-in and a plan that includes the API. The full secret is shown once; Folio stores only a hash, so a lost key cannot be recovered, only replaced.
To rotate, use Rotate in the console. It issues a replacement with the same name, scopes and settings, and the old key keeps working for a grace period (24 hours by default) so you can deploy the new one without downtime. Revoking a key takes effect at once.
Each key shows when and from where it was last used and how many requests it has made. A key nobody uses is a key to revoke.
Keep keys secret#
- Keys belong on a server. Never put one in a web page, a mobile app or a URL.
- Keep them in your secret store, not in source control.
- The browser-safe credential is the widget site key, which only works from origins you allow. See widget.
- If a key leaks, revoke it from the console, then create a replacement.
Verified against API version 0.0.0-dev. Generated from the live OpenAPI document.