Skip to main content

​
Overview

Pingtree uses token-based authentication to secure all API integrations. Tokens are required by any external system submitting leads, pings, or posts to your organization. You can manage tokens at three levels: organization-wide, per campaign, and per source. Navigate to Settings > Token Management to view and manage all tokens.

​
Token Levels

Token LevelScopeBest For
Global TokenEntire organizationSimple setups with a single integration point
Campaign TokenA single campaignIsolating traffic from different campaigns
Source TokenA specific source (CS, MP, MC)Granular control per traffic source

​
Global Token

The global token is a single API token that authenticates requests across your entire organization. When enabled, any API call using this token is accepted regardless of which campaign or source it targets.

​
Enabling Global Token Authentication

  1. Go to Settings > Token Management.
  2. Toggle Global Token Authentication to on.
  3. Copy the token value and share it with your integration partner.

​
When to Use a Global Token

  • You have a single integration sending leads across multiple campaigns.
  • You want a simple setup without managing separate tokens per campaign or source.
Tip: Global tokens are convenient but offer less isolation. If one integration is compromised, all campaigns are exposed. Consider campaign or source tokens for higher-security setups.

​
Campaign-Wise Tokens

Campaign tokens provide an isolated authentication layer for each campaign. If you enable campaign-wise token authentication, only requests carrying that campaign’s token will be accepted.

​
Setting Up Campaign Tokens

  1. Open the campaign you want to configure.
  2. Go to Settings > Token Management within the campaign.
  3. Enable Campaign Token Authentication.
  4. Copy the generated token and provide it to the traffic source sending leads to that campaign.
This ensures that traffic intended for Campaign A cannot accidentally post to Campaign B, even if someone has the wrong endpoint URL.

​
Source Tokens

Source tokens are the most granular level of authentication. Each source (Custom Source, Marketing Partner, or Media Channel) can have up to three distinct tokens depending on the submission method:
Token TypeAPIDescription
Form TokenForm Submission APIUsed when leads are submitted via a standard form post
Ping TokenPing APIUsed for the ping step in a ping-post flow
Post TokenPost APIUsed for the post step in a ping-post flow

​
Setting Up Source Tokens

  1. Open a campaign and navigate to the source you want to configure.
  2. Go to the Tokens tab within the source settings.
  3. Enable the token types you need (Form, Ping, Post).
  4. Copy each token and share with your traffic partner.

​
Regenerating Tokens

Any token — global, campaign, or source — can be regenerated at any time. Regenerating a token immediately invalidates the old one, so any integration using the old token will stop working until it is updated.

​
How to Regenerate a Token

  1. Locate the token you want to rotate.
  2. Click Regenerate next to the token.
  3. Confirm the action in the prompt.
  4. Copy the new token and update your integration.
Important: Regenerating a token is immediate and cannot be undone. Make sure you have access to update all integrations using that token before regenerating.

​
Token Authentication Flow

When an external system sends a lead to Pingtree, the platform checks authentication in this order:
  1. Source Token — If the source has a token enabled, the request must include the matching token.
  2. Campaign Token — If no source token is configured but a campaign token is enabled, the campaign token is checked.
  3. Global Token — If neither source nor campaign tokens are configured but global token auth is enabled, the global token is checked.
  4. No Auth — If no token authentication is enabled at any level, the request is accepted without a token.

​
Security Best Practices

  • Rotate tokens regularly, especially after team changes or integration updates.
  • Use source-level tokens for external traffic partners so each partner has their own isolated credential.
  • Never share tokens in public repositories, emails, or chat messages. Use a secure credential manager.
  • If a token is suspected to be compromised, regenerate it immediately and notify your integration partner.