Developers
API keys and scopes
An API key lets a program act for your church through the REST API or the MCP server. Each key belongs to one church and carries only the scopes you give it.
On this page
Create a key #
- Sign in to the admin as an admin or owner, with two-step sign-in.
- Open Settings → API keys.
- Give the key a name that says where it's used, such as “Planning Center sync” or “Claude Desktop, Sarah's laptop”.
- Tick only the scopes it needs. With a giving scope, a note reminds you that the key can read givers' names, emails and gifts, so use it only from a server your church controls.
- Tick the box to agree to the API terms on behalf of your church. Your acceptance is recorded with the key.
- Create it, and copy the key straight away. It's shown once and can't be shown again.
Keys look like ml_live_ followed by 32 letters and digits. The list of keys shows each one's name, its first few characters, its scopes, when it was created and when it was last used.
Scopes #
| Scope | Lets the key |
|---|---|
gallery:read | Read the public gallery: what visitors can see. |
missionaries:read | Read missionary records, including fields that aren't public. |
missionaries:write | Add and update missionary records. Includes missionaries:read. |
newsletters:write | Add newsletters to a missionary. |
announcements:write | Post announcements. |
giving:read | Read giving totals and where a month's gifts went. |
giving:write | Import gifts and set a month's payments. Includes giving:read. |
The exact scope each endpoint and tool needs is listed in the API reference and on the MCP server page.
Revoke a key #
In Settings → API keys, revoke a key you no longer use, or one that may have been seen by someone else. It stops working at once. Create a new key to replace it.
Keeping keys safe #
- Treat a key like a password. Anyone who has it can do what its scopes allow, for your church.
- Give each program its own key, with the fewest scopes it needs, so you can revoke one without breaking the others.
- Keep keys out of web pages, shared documents and code you publish. A key with
givingormissionariesscopes can read private details. - Missionary Lane stores only a one-way fingerprint (an HMAC-SHA256 hash) of each key, never the key itself, so nobody, including the Missionary Lane team, can show it to you again.
- Creating and revoking keys, and every change made with a key, are recorded in an audit log. The key itself never is.