API keys

Every programmatic integration with GCM authenticates with an API key. Zapier uses one. Your custom backend uses one. Your data warehouse pipeline uses one. This page covers how to create, scope, and retire them safely.

Manage keys under Integrations → Zapier → API Keys. (Despite the URL, this isn't just for Zapier — any external caller of the GCM API uses keys from here.)

Creating a key

Click New key. Give it a label that names what will use the key, not who created it:

• Zapier — Production — for Zaps.
• Data warehouse ETL — for your nightly export job.
• Internal directory site — for a staff-only intranet that lists members.

When you click create, GCM displays the raw key once.

Copy it immediately and store it in a real secret manager — 1Password, AWS Secrets Manager, Doppler, Vault, your platform of choice. Do not paste it into Slack, email, or a wiki page.

WARNING

We do not store the raw key. The database holds only a hash, plus a 6-character prefix you can use to identify which key is which without revealing the secret. If you lose the raw key, your only option is to revoke and reissue.

Key format

Keys look like gcm_live_<32 random characters> or gcm_test_<32 random characters> depending on the environment they were minted in. The prefix is visible in the keys list so you can tell at a glance which key is production vs staging without ever seeing the secret.

gcm_live_a1b2c3d4e5f6...
└─┬─┘└─┬─┘└──────┬──────┘
  │    │         └── 32 chars of CSPRNG entropy
  │    └── environment
  └── product (always `gcm`)

Scopes

Every key carries a list of scopes that constrain what it can do. The default for keys created through the Zapier UI is read:* — read-only access to every resource.

Scope	Grants
read:*	List and read every public resource
read:members	Members only
read:donations	Donations only
write:members	Create / update members
write:donations	Record donations (for accounting integrations)
subscriptions:manage	Create / delete webhook subscriptions
*	Full access — admin-equivalent. Use sparingly.

Scopes are enforced by the API gateway, not the application logic — a read:* key calling a write endpoint gets a 403 immediately, never reaches the underlying RPC.

TIP

Start every new integration on read:*. Only widen the scope when you've proven the read path works and you have an actual write requirement. Over-scoped keys are how exploits become catastrophes.

Using a key

Send the key as a Bearer token on every request:

curl https://api.geniuschurchmanager.com/v1/members \
  -H "Authorization: Bearer gcm_live_..."

That's it. No OAuth dance, no per-request signing — just the bearer. Combined with HTTPS this is sufficient for the integrations the API is designed for.

Every request is logged with the key prefix, the endpoint hit, and the response status. You can see the last-used timestamp on the key in the GCM UI — useful for spotting keys that haven't been used in months (good candidates for rotation or revocation).

Rotation

You should rotate API keys:

• On schedule — every 12 months at minimum.
• On staff departure — anyone who had access to the raw key should not be able to use it after they leave.
• On suspected compromise — if a key shows up in a Git commit, a Slack message, or a screenshot, treat it as compromised.

Rotation procedure:

1. Mint a new key with the same scopes.
2. Deploy the new key into the consumer (Zapier connection, env var, secret manager).
3. Verify the consumer is using the new key by watching the last_used timestamp move.
4. Revoke the old key.

GCM does not currently support overlapping rotation windows — the old key works until you revoke it, and the new key works from the moment of creation. Plan your cutover.

Revoking

Hit the trash icon next to any key. The key is marked revoked_at immediately; the very next request bearing it gets a 401.

WARNING

Revoking a key in production breaks any consumer using it instantly. Zaps stop, your ETL job throws, your intranet directory site goes blank. Coordinate the rotation, then revoke.

Revoked keys stay in the list (greyed out) so you can audit when they were issued, when they were last used, and when they were retired. To permanently delete an old revoked key, contact platform support — auditors generally prefer revocations to deletions.

Auditing usage

The keys list shows for each key:

• Created timestamp.
• Last-used timestamp (rolling — updates within seconds of a request).
• Scopes.
• Revoked timestamp, if revoked.

For deeper auditing — per-endpoint counts, response code distribution, abuse detection — platform admins have access to the api_request_log table in BigQuery exports. Reach out if you need a specific slice.

Limits

Limit	Default
Keys per org	20
Requests per second per key	60
Requests per hour per key	10,000
Concurrent requests per key	20

These limits are deliberately generous for legitimate integrations and tight enough to make brute-force enumeration impractical. If you bump into a limit, you likely have a runaway loop somewhere.

What an API key cannot do

For safety, API keys deliberately can not:

• Sign in interactively (no session, no UI access).
• Manage other API keys (only the Zapier UI can, and only admins reach it).
• Impersonate users (the JWT system that gates platform-admin impersonation is separate).
• Bypass row-level security — every query still scopes to current_org_id() derived from the key's org.

These are guardrails, not features: even a compromised key can't escalate beyond the org that owns it.

Cross-references

• Zapier integration — the most common consumer of these keys.
• Outbound webhooks — uses the same keys to create subscriptions.
• API authentication — full API reference for using a key.