Private Integrations and API Tokens in Sparkforge

Private Integrations let you build secure, custom connections between Sparkforge and any third-party app. They're the right tool for internal workflows and bespoke integrations that don't need a full public app listing.

For the full endpoint reference and request/response details, see the developer docs at https://marketplace.sparkforge.com/docs/.

What is a Private Integration?

If you want to connect Sparkforge to a third-party app, you have two options:

• Install an app from the App Marketplace.
• Build your own with a Private Integration token and the API.

Private Integrations cover option two. They're scope-restricted, generated from the UI, and easy to rotate.

Private Integrations vs. legacy API Keys

Private Integrations vs. OAuth2 access tokens

How to call the API

Pass the token in the Authorization header. Example: get a sub-account's details with the agency's token.

curl --request GET \
  --url https://services.sparkforgehq.com/locations/ve9EPM428h8vShlRW1KT \
  --header 'Accept: application/json' \
  --header 'Authorization: <YOUR PRIVATE INTEGRATION TOKEN>' \
  --header 'Version: 2021-07-28'

Test by creating a contact

curl --request POST \
  --url https://services.sparkforgehq.com/contacts/ \
  --header 'Authorization: <YOUR PRIVATE INTEGRATION TOKEN>' \
  --header 'Content-Type: application/json' \
  --header 'Version: 2021-07-28' \
  --data '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "locationId": "LOCATION_ID"
  }'

Replace LOCATION_ID with the actual sub-account ID and Authorization with your token.

Who can create Private Integrations

By default, all agency admins can create and manage them. Restrict per-user under Settings → Team → edit the admin → Roles & Permissions. Two restriction levels exist:

• View and manage the agency's Private Integrations.
• View and manage the sub-accounts' Private Integrations.

Private Integrations are available to both agencies and sub-accounts. If you don't see them under settings, enable the feature in Labs.

Create a Private Integration

1. Go to Settings → Private Integrations and click Create new Integration.
2. Give it a name and description.
3. Select only the scopes the integration needs. Less is more secure.
4. Copy the token. You cannot view it again later.
5. Share it only with trusted developers.

Up to 5 Private Integration tokens can exist at the agency level and at the location level.

Rotate a token

Rotate every 90 days as a baseline.

1. Open the Private Integration.
2. Click Rotate and expire this token later.
3. Confirm.
4. Copy the new token and update the third-party app.

The old and new tokens both work for 7 days. During that window you can Cancel rotation if the developer needs more time, or Expire Now if the third-party app is already updated. After 7 days, the old token expires automatically.

Token compromised?

1. Open the Private Integration.
2. Click Rotate and expire this token now.
3. Confirm.
4. Copy the new token and update the third-party app.

Edit name, description, or scopes

You can edit a Private Integration's name, description, and scopes without generating a new token. Open the three-dot menu, click Edit, update the fields, and save. The existing token keeps working.

Delete a Private Integration

Open the three-dot menu and pick Delete. The token stops working immediately. Use this when you no longer need the third-party app.