Authentication

Every request carries one of your organisation’s secret keys as a bearer token:

Authorization: Bearer cp_live_…

X-API-Key: cp_live_… works too.

Test and live keys

Key	Works on
cp_test_…	The sandbox: your organisation’s sandbox account, with no real money
cp_live_…	Your organisation’s real account

The key decides the mode; the addresses are the same. Every response and webhook says which mode it belongs to.

Creating and managing keys

An admin of your organisation creates keys in the CatholicPay portal, under Developers → Keys. Each key has:

• A mode: test or live. Live keys are available once your organisation is live.
• Whether it can move money. A key that cannot only reads and takes payments. Transfers, wallet charges and withdrawals need a key created with can move money; creating a live one asks the admin for their PIN and a code sent to their phone, and your other admins and signers are told.
• An optional IP allow-list and rate limit (Rate limits).
• A label, and when and from where it was last used.

A key is shown once, when it is created; CatholicPay keeps only a hash of it. If you lose a key, create a new one and revoke the old. Revoking takes effect at once.

Keeping keys safe

• Use keys only from your servers. Never put a secret key in a mobile app, website or anything a user can download. The API has no public keys: payers pay on CatholicPay’s own pages (Card checkout).
• Keep keys in a secrets manager or environment variables, never in source control.
• Give each system its own key, with only the rights it needs, and an IP allow-list where you can.
• Roll keys periodically, and at once if one may have leaked.

Errors

Status	code	Why
401	UNAUTHENTICATED	No key, or not a valid one (revoked, mistyped)
403	FORBIDDEN	The API is switched off for your organisation, or the key may not do this (for example, move money)
403	IP_NOT_ALLOWED	The key does not work from this address
422	NOT_LIVE	A live key used before your organisation is live