Authentication

Overview

All API services are protected by HTTP Basic Authentication over HTTPS. Every request must include valid credentials. Requests over plain HTTP (port 80) will be redirected to HTTPS.

Credentials

API logins and passwords are created and managed through the API Admin section within the Pushpay ChMS software. These credentials are separate from API User Community accounts.

Each login can be assigned access to individual services, giving you granular control. For example, an integration that only needs event data does not need access to financial services.

Please see this Pushpay Help Center article on how to create an API user within ChMS.

HTTP Basic Authentication

The API uses the standard HTTP Basic Authentication scheme. Credentials are sent in the Authorization header as a Base64-encoded username:password string.

Using curl

Pass credentials with the -u flag:

curl -u username:password "https://yourchurch.ccbchurch.com/api.php?srv=api_status"

curl handles the Base64 encoding and Authorization header automatically.

Raw HTTP Header

If your HTTP client does not support Basic Auth natively, construct the header manually:

Combine the username and password with a colon: username:password
Base64-encode the combined string
Set the Authorization header with the Basic scheme

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Verifying Access

Use the api_status service to verify your credentials are working without consuming your daily API call quota:

curl -u username:password "https://yourchurch.ccbchurch.com/api.php?srv=api_status"

This returns your daily_limit, last_run_date, and current counter without incrementing the call count.

Authentication Errors

Code	Description
1	`API_MESSAGE_INVALID_CONNECTION` — The API must be accessed with a secure connection (HTTPS).
2	`API_MESSAGE_INVALID_LOGIN_OR_PASSWORD` — Invalid username or password.
3	`API_MESSAGE_API_NOT_ACTIVE` — API functionality not active for your organization.
110	`API_MESSAGE_PERMISSION_NO_ACCESS` — You do not have permission to use this service. Contact your system administrator.
111	`API_MESSAGE_PERMISSION_NO_PRIVATE_ACCESS` — The service is restricted and requires purchased permission.

Security Considerations

Always use HTTPS (port 443). The API does not accept unencrypted connections.
Do not embed credentials in client-side code or public repositories.
Create separate API logins per integration so access can be revoked independently.
Assign only the services each integration requires.