Authentication

Authentication to the API is done through an Authorization Bearer token. Every request should have this implemented within the request headers.

curl https://api.textinchurch.com/API/1_0/getMe.php \
  --header 'authorization: Bearer ACCESS_TOKEN'

There are a few different ways to obtain the token to access the API depending on whether you are accessing the API for your personal or organization use, or if you are building a third-party application that will be used by Text In Church users to access their own data.

Personal API Key

A personal API key is used to access your own account for your own purposes. For example, if you were creating a script to find and merge duplicate contact records. To create an API key, login to your Text In Church account via the browser-based application. Under "Account Settings", you see "Developer API". There you can create API keys. If you do not see the "Developer API" area, please contact support to request access. You can do so through our Help Center.

To use the API Key, just pass it to the API in the header of your request as the authorization bearer token.

🚧

IMPORTANT: Do not share Personal API Keys with anyone outside your organization. Also, do not embed them in client-side code. The API key is equivalent to a username and password.

OAuth 2.0

If you are creating an application that will be distributed to multiple users of Text In Church so they can leverage their own data on your platform, you will need to use OAuth to do so. Text In Church conforms to the Authorization Code flow in OAuth version 2.0.

To get going:

1. You will need to have a Text In Church account to represent your organization.
2. Contact support to request access to the developer area. You can do so through the Help Center.
3. In the Developer Area, create a new OAuth application.

Setting up OAuth.

(1) Authorize the user by redirecting them from your application to Text In Church with the following parameters: client_id, redirect_uri, response_type, scope.

https://api.textinchurch.com/API/1_0/oauthorize.php
	?client_id=CLIENT_ID
	&redirect_uri=https://your-application/callback
	&response_type=code

(2) When the user reaches the Text In Church application, they will be presented with a login form. Once they login and grant permission, Text In Church will redirect the user back with a single-use authorization code.

HTTP/1.1 302 Found
Location: https://your-application/callback?code=AUTHORIZATION_CODE

(3) Using the authorization code returned by Text In Church, make a request to the API to exchange the code for an access token. This requires sending the grant_type, authorization_code, client_id, client_secret, and redirect_uri to the authorization endpoint. NOTE: An authorization code may only be used one time.

curl -X POST https://api.textinchurch.com/API/1_0/oauthorize.php \
  --data 'grant_type=authorization_code' \
  --data 'client_id=CLIENT_ID' \
  --data 'client_secret=CLIENT_SECRET' \
  --data 'code=AUTHORIZATION_CODE' \
  --data 'redirect_uri=https://your-application/callback'

(4) Text In Church will verify the authorization code, client ID, and client secret. Text In Church will respond with an access token and refresh token.

{
  "access_token": "<access token>",
  "token_type": "bearer",
  "expires_in": 7200,
  "refresh_token": "<refresh token>",
  "scope": "people",
  "created_at": 1469553476
}

(5) Your application can use the access token as a Bearer token in the Authorization header of your HTTP request.

curl https://api.textinchurch.com/API/1_0/getMe.php \
  --header 'authorization: Bearer ACCESS_TOKEN'

(6) You can use the Refresh Token to get a new access token. Usually, a user will need a new access token only after the previous one expires or when gaining access to a new resource for the first time. It's bad practice to call the endpoint to get a new access token every time you call an API. Please take note, the refresh token will change once used.

curl -X POST https://api.textinchurch.com/API/1_0/oauthorize.php \
  --data 'grant_type=refresh_token' \
  --data 'client_id=CLIENT_ID' \
  --data 'client_secret=CLIENT_SECRET' \
  --data 'refresh_token=REFRESH_CODE' \
  --data 'redirect_uri=https://your-application/callback'

RESPONSE:

{
  "access_token": "<new access token>",
  "token_type": "bearer",
  "expires_in": 7200,
  "refresh_token": "<new refresh token>",
  "created_at": 1540325919
}