Overview We use OAuth 2.0 to secure our endpoints so you will need to talk with Pushpay (Church Community Builder) to get an application created.

To request access please fill out this form https://vendor.ccbchurch.com/goto/forms/15/responses/new

API Base URL

All api calls must be made against https://api.ccbchurch.com and not https://[subdomain].ccbchurch.com.

Authentication

The authentication mechanism offered to Vendors and Churches to authorize the use of a given church's data is the three-legged OAuth flow. We offer two different auth types to authorize the church (System Auth) or authorize an individual in the church (Identity Auth).

System Auth

This will be the first step to gain access to a church's data. The Master Administrator or a person with the ability to Edit System Wide Settings for a church can authorize a vendor to use their data. Without this authorization the vendor will not be able to access the church's data.

Authorization URL: https://oauth.ccbchurch.com/oauth/authorize
Token URL: https://api.ccbchurch.com/oauth/token (Make sure to provide the Accept header set to application/vnd.ccbchurch.v2+json)

Sandbox Sites

The api is on https://api-beta.ccbchurch.com and the auth server is on https://beta-oauth.ccbchurch.com/ for "sandbox" ChMS sites.

Query String Parameters

Parameter		Description
subdomain	Optional	If provided will bypass the church's subdomain step in the flow
client_id	Required	OAuth Client Id provided by Pushpay
response_type	Required	Must always equal `code`
state	Optional	Unique identifier to protect against CSRF, and is recommended
scope	Optional	This is what data your application can access. This can be a subset of the requested scopes when you set up your OAuth Application with Pushpay. If you do not provide this parameter then it will default to all scopes assigned when you requested API credentials.
redirect_uri	Required	Must match the redirect provided to Pushpay when the OAuth Application was created

Steps to get an Access Token

Redirect to the Authorization URL with the required parameters
Master Administrator or Edit System Wide Settings will
1. Provide the subdomain if not provided in the original redirect
2. Login to their Pushpay site if not already logged in
3. Review the list of requested scopes and authorize the vendor to use them on their site
Pushpay will redirect to the redirect_uri parameter provided when the OAuth application was created
Post to the Token URL with grant_type=authorization_code and code equal to the returned code from the previous step
This will return the access token model provided in the model section
Subsequent requests to the API are capable by providing the Authorization header with the Access Token as the Bearer token

Identity Auth

This auth flow is similar to the System Auth flow without the need for the authorization step. In order to use this Auth Flow the church administration will need to authorize the vendor using the System Auth Flow first.

This is to perform API requests on behalf of the individual authenticated through this flow. Any permissions the authenticated individual has will be taken into account when API calls are made. This will allow you to add a login with Pushpay link within your application.

Authorization URL: https://oauth.ccbchurch.com/oauth/authorize
Token URL: https://api.ccbchurch.com/oauth/token

Query String Parameters

Parameter		Description
resource_owner_auth	Required	If provided will perform the Identity Auth instead of the System Auth flowy
system auth flow parameters	see above	All other parameters from System Auth Flow apply here with Identity Auth Flow

Additional Resources

Please see this article for more information about OAuth security.