Overview We use OAuth 2.0 to secure our endpoints so you will need to talk with 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) Query String Parameters subdomain Optional If provided will bypass the church's subdomain step in the flow client_id Required OAuth Client Id provided by Church Community Builder, Inc response_type Required Will always equal code state Optional Unique identifier to protect against CSRF scope Optional This is what data your application can access A subset of requested scopes when you setup your OAuth Application with Church Community Builder By default if you do not provide this parameter it will default to the scopes you requested redirect_uri Required Must match the domain provided to Church Community Builder 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 Provide the subdomain if not provided in the original redirect Login to their Church Community Builder site if not already logged in Review the list of requested scopes and authorize the vendor to use them on their site Church Community Builder 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 Church Community Builder link within your application.

• Authorization URL: https://oauth.ccbchurch.com/oauth/authorize
• Token URL: https://api.ccbchurch.com/oauth/token
• Query String Parameters
  • Same as System Auth Flow
  • resource_owner_auth
    • boolean
    • If provided will perform the Identity Auth instead of the System Auth flow

Additional Resources

Please see this article for more information about OAuth security.