OAuth Authentication

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

To request access, please fill out the API access request form.

API Base URL

All API calls must be made against:

https://api.ccbchurch.com

Do not call https://[subdomain].ccbchurch.com directly.

Authentication Overview

The mechanism offered to vendors and churches for authorizing access to a church's data is the three-legged OAuth flow.

Auth Type	Purpose
System Auth	Authorizes the vendor to access an entire church's data

System Auth

This is the required first step to gain access to a church's data. A Master Administrator, or someone with permission to edit system-wide settings, must authorize your application before you can access that church's data.


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

Sandbox Environment

For "sandbox" ChMS sites using sandbox API credentials, use:

Sandbox credentials required
Only sandbox specific API credentials will work with the sandbox servers.


API	`https://api-beta.ccbchurch.com`
Auth server	`https://beta-oauth.ccbchurch.com/`

Query String Parameters

Parameter	Required?	Description
`subdomain`	Optional	Bypasses the church's subdomain-entry 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 (recommended)
`scope`	Optional	Space-separated list of scopes your app can access. Must be a subset of the scopes granted when your OAuth application was created. Defaults to all granted scopes if omitted
`redirect_uri`	Required	Must exactly match the redirect URI registered with Pushpay for this OAuth application

Steps to Get an Access Token

Redirect the user to the Authorization URL with the required parameters.
The Master Administrator (or an admin with system-wide settings access) will:
- Provide the subdomain, if it wasn't included in the original redirect
- Log in to their Pushpay site, if not already logged in
- Review the requested scopes and authorize the vendor to use them
Pushpay redirects back to your redirect_uri with an authorization code.
POST to the Token URL with:
- grant_type=authorization_code
- code — the value returned in the previous step
Pushpay returns an access token (see the token model reference).
Use the access token as a Bearer token in the Authorization header for all subsequent API requests.

Refreshing Tokens

Access Tokens expire every two (2) hours. You can use the refresh token, provided to you in the response when you first authorize and request the initial token.

{
  "access_token": "{access token}",
  "token_type": "bearer",
  "expires_in": 7200,
  "scope": "{scopes}",
  "refresh_token": "{refresh token}"
}

To refresh your token, POST to the Token URL with:

grant_type=refresh_token
refresh_token= the refresh token value returned from the previous token response

For more information on refreshing tokens, please see this article:

https://www.oauth.com/oauth2-servers/access-tokens/refreshing-access-tokens/

Additional Resources

OAuth flow to get an access token
Demystifying OAuth Security: State vs. Nonce vs. PKCE — background on OAuth security best practices