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. Two auth types are available:

Auth Type	Purpose
System Auth	Authorizes the vendor to access an entire church's data
Identity Auth	Authorizes API requests on behalf of an individual within the church

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, use:


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.

Identity Auth

This flow is similar to System Auth, but skips the authorization step. Identity Auth requires that the church has already completed System Auth to authorize the vendor.

Use this flow to make API requests on behalf of a specific individual — the permissions of that authenticated person are applied to each request. This is what powers a "Login with Pushpay" experience in your application.


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

Query String Parameters

Parameter	Required?	Description
`resource_owner_auth`	Required	Set to trigger Identity Auth instead of System Auth
(all System Auth parameters)	—	All other parameters from the System Auth flow also apply here

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

Demystifying OAuth Security: State vs. Nonce vs. PKCE — background on OAuth security best practices