Build an Integration

for Partner Applications to gain access to an Organization’s Kindful account via the API

To create an application that Kindful customers can connect to their accounts, you will need a Kindful Partner Account.

Create OAuth2 Application

  • Once you have access to create an application, click "*Create Application".
  • Here you name your application
  • Click "Create".
  • Once created, click "Manage Application" on your Application in the Applications Page.
  • Click "Playground" to Generate OAuth2 Credentials for your application on the Playground environment.

Scopes

Based on your integration requirements, set the Scope to any/all of the following:

  • basic -- Access Kindful Account details. Allows all GET requests and setting integration status.
  • data_add -- Create & update records in Kindful.
  • data_query -- Access Contact and Transaction records in Kindful.
Authorization: Bearer <copy token here>
Content-Type: application/json

Crafting the Authorize URL

The URL to initiate authorization should contain client_id, response_type, redirect_uri, and scope

If you are testing in the Playground environment first, format all API calls starting with https://app-playground.kindful.com/...

https://app.kindful.com/admin/oauth2/authorize?client_id=CLIENT_ID&response_type=code&redirect_uri=REDIRECT_URI&scope=SCOPE_SPACE_DELIMITED
{
	code: KINDFUL_GENERATED_CODE
}

Upon a user successful signing into a Kindful account and authorizing your application, an authorization code will be sent back which you can then use to retrieve an OAuth token.

Retrieving the OAuth token

Once you have received the authorization code, you need to hit the Kindful API to retrieve an OAuth token. This is what you will use for all future API requests.

POST https://app.kindful.com/admin/oauth2/token
	--client_id: CLIENT_ID
  --client_secret: CLIENT_SECRET
  --code: CODE
  --grant_type: 'authorization_code'
  --redirect_uri: REDIRECT_URI
{
  "access_token": "ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": "2508735",
  "scope": "basic",
  "created_at": "1474577889"
}

Refresh Access Token

Your access_token does not expire, but if you would like to refresh it, you can do so using the refresh_token sent over with the initial access_token. Refreshing a token uses the same endpoint as generating an access token.

https://app.kindful.com/admin/oauth2/token

grant_type

It is important to note that your grant_type must be of type refresh_token.

Refresh Token Request

{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "grant_type": "refresh_token",
  "refresh_token": "YOUR_REFRESH_TOKEN"
}

Refresh Token Response

{
  "access_token": "ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": 2591878,
  "refresh_token": "REFRESH_TOKEN",
  "scope": "SET_SCOPES",
  "created_at": 1473974737
}

Revoking Access / Disconnect

We recommend that you provide a URL for the user to hit, which would revoke the token from the user in order to disconnect and disallow any further authorized calls to transpire.

Attempts to call the Kindful API after a user has disconnected your application will return:

{
    "valid": false,
    "errors": [
        "Disabled integration"
    ]
}