Platform Connections

Platform connections are the bridges between AudienceGPT and external systems. An inbound connection pulls topic data from an external API into your library. An outbound connection pushes classified segments to demand-side platforms (DSPs) for activation. Each connection stores its platform type, authentication credentials, and configuration -- everything needed to communicate with the external system without re-entering details each time.

Understanding Connection Types

AudienceGPT supports three connection directions:

Direction	Purpose	Example Use Case
Inbound	Pull topics from an external API into AudienceGPT	Sync audience segments from a DMP or internal taxonomy service
Outbound	Push classified segments to a DSP or delivery platform	Activate segments on LiveRamp, Trade Desk, or Index Exchange
Bidirectional	Both pull and push on the same connection	Sync topics from a platform and push activated segments back to it

Most organizations use separate inbound and outbound connections. Inbound connections are used for the Sync workflow, and outbound connections are used for Segment Activations.

Supported Platforms

AudienceGPT has built-in support for four platform types, each with platform-specific configuration and credential requirements.

LiveRamp

LiveRamp connections use OAuth2 authentication with the LiveRamp Data Marketplace Provider API. LiveRamp is supported as an outbound connection for segment activation.

Field	Description
Token URL	LiveRamp OAuth2 token endpoint (defaults to https://serviceaccounts.liveramp.com/authn/v1/oauth2/token)
API Base URL	LiveRamp API base (defaults to https://api.liveramp.com)
Default CPM	Default cost-per-thousand for activated segments
Currency	Pricing currency (e.g., USD)
Data Source Location	LiveRamp data source location identifier

Credentials required: Username, Password, Client ID, Organization ID (from your LiveRamp service account).

Trade Desk

Trade Desk connections use API key authentication with the Trade Desk Taxonomy API. Trade Desk is supported as an outbound connection for segment activation.

Field	Description
API Base URL	Trade Desk API base (defaults to https://partners.thetradedesk.com/api/v3)
Default CPM	Default cost-per-thousand for activated segments
Currency	Pricing currency (e.g., USD)

Credentials required: API Key, Provider ID, and optionally a Brand ID for Data Alliance connections.

Index Exchange

Index Exchange connections support both SFTP and S3 upload methods. Index Exchange is supported as an outbound connection for segment file delivery.

Field	Description
Account ID	IX account ID (used in meta files as ownerAccount_id)
Advertiser Account ID	Advertiser account identifier for meta files
Match Key	Determines which SFTP folder to upload into. Options: ip, url, deviceid, uid, appbundle, contentid, postalcode
Upload Method	sftp for direct SFTP upload or s3 for S3 bucket delivery
S3 Bucket	S3 bucket name (only when upload method is S3)
S3 Role ARN	IAM role ARN for S3 access (only when upload method is S3)
Default CPM	Default cost-per-thousand for activated segments
Currency	Pricing currency (e.g., USD)

Credentials required (SFTP): SFTP Host, Username, Password, and optionally Port (defaults to 22).

Custom API

Custom API connections provide a flexible configuration for any platform with a REST API. They support all authentication types and can be configured for both inbound and outbound use.

Field	Description
Base URL	The root URL of the external API
Response Path	JSON path to extract topic records from the API response (e.g., data.segments)
Count Endpoint	Endpoint to fetch total record count (for pagination)
Count Response Path	JSON path to extract the count value
Pagination Type	offset or cursor based pagination
Pagination Params	Limit/offset parameter names and page size
Field Mappings	Map source API fields to AudienceGPT topic fields
Filters	Key-value pairs appended as query parameters
Extra Headers	Additional HTTP headers sent with every request
Sync Mode	full (re-fetch all records) or incremental (only new/changed records)

Creating a Connection

Navigate to the Connections section from the sidebar (available on the Sync or Activate pages). Click New Connection to open the connection creation form.

Connection Form Fields

The form uses progressive disclosure -- fields appear based on your selections.

Step 1: Basic Information

Field	Required	Description
Name	Yes	A descriptive name for this connection (e.g., "LiveRamp Production", "Internal DMP Sync")
Platform	Yes	Select from: LiveRamp, Trade Desk, Index Exchange, Custom API
Direction	Yes	Inbound, Outbound, or Bidirectional

Step 2: Authentication

The available authentication types depend on the selected platform:

Auth Type	How It Works	Available For
OAuth2	Client credentials grant; tokens are automatically refreshed	LiveRamp
Bearer	Static bearer token sent in the Authorization header	Custom API
API Key	Key sent as a header or query parameter	Trade Desk, Custom API
Header	Custom header name and value pair	Custom API
None	No authentication required	Custom API

Step 3: Credentials

Enter the credentials required for your chosen auth type. The specific fields depend on the platform:

• LiveRamp: Username, Password, Client ID, Organization ID
• Trade Desk: API Key, Provider ID, Brand ID (optional)
• Index Exchange (SFTP): SFTP Host, Username, Password, Port
• Custom API (Bearer): Token value
• Custom API (API Key): Key name, Key value
• Custom API (Header): Header name, Header value

warning

Credentials are encrypted at rest using pgcrypto symmetric encryption and are never returned in API responses after creation. If you need to update credentials, you must re-enter them entirely -- the system does not display existing credential values.

Step 4: Platform Configuration

Platform-specific configuration fields appear based on your platform and direction selections. For outbound connections, this includes CPM pricing, currency, and API base URLs. For inbound connections, this includes API endpoints, response paths, field mappings, and pagination configuration.

Saving the Connection

Click Save Connection to create the connection. The system validates that all required fields are populated and that the configuration structure is correct. If validation passes, the connection is created and appears in your connections list.

info

Each organization can have up to 20 connections across all platforms and directions. Contact support if you need a higher limit.

Testing Connections

After creating a connection, you should verify that AudienceGPT can communicate with the external platform. Click the Test Connection button on the connection detail panel.

The test operation performs a lightweight verification:

• OAuth2 (LiveRamp): Requests an access token using the stored credentials. Success confirms the credentials are valid and the token endpoint is reachable.
• API Key (Trade Desk): Makes a minimal API call to verify the key is accepted.
• SFTP (Index Exchange): Establishes an SFTP session to confirm host, username, and password are correct.
• Bearer/Header/None (Custom API): Sends a request to the configured base URL and verifies a successful HTTP response.

Test results are displayed immediately:

Result	Meaning
Connection Successful	Credentials are valid and the platform is reachable
Authentication Failed	Credentials were rejected by the platform -- verify and re-enter them
Connection Timeout	The platform did not respond within the timeout window (30 seconds for most platforms)
Network Error	The platform URL is unreachable -- check the URL and network configuration

tip

Always test a new connection before using it for sync or activation operations. A failed test prevents wasted time on operations that will fail at the credential step.

Managing Connections

Viewing Connections

Your connections list shows all configured connections with their platform, direction, status (enabled/disabled), and last-used timestamp. Click any connection to view its full configuration.

Editing a Connection

Click Edit on a connection to modify its configuration. You can change:

• Connection name
• Platform configuration (URLs, CPM, currency, etc.)
• Authentication credentials (must re-enter entirely)
• Enabled/disabled status

You cannot change the platform type or direction of an existing connection. To change these, create a new connection and delete the old one.

Disabling a Connection

Toggle the Enabled switch to disable a connection without deleting it. Disabled connections:

• Cannot be used for new sync or activation operations
• Retain all configuration and credentials
• Can be re-enabled at any time

Deleting a Connection

Click Delete to permanently remove a connection. This action:

• Removes the connection configuration and encrypted credentials
• Does not deactivate any segments that were pushed through this connection (those remain active on the DSP)
• Cannot be undone

warning

Deleting an outbound connection does not automatically deactivate its segments on the external platform. Deactivate segments explicitly before deleting the connection if you want to remove them from the DSP.

Credential Security

AudienceGPT takes credential security seriously. All authentication credentials are encrypted using PostgreSQL's pgcrypto extension with symmetric encryption (AES-256) before being stored in the database.

Security measures include:

• Encryption at rest: Credentials are encrypted with the CREDENTIALS_ENCRYPTION_KEY environment variable before being written to the platform_connections table. The key is never stored in the database.
• No credential return: API responses for connection records never include decrypted credential values. The authCredentials field is omitted from all GET responses.
• Re-entry required: When updating credentials, you must provide the complete new credential set. There is no "update one field" option, as the system cannot display existing values for partial editing.
• Server-side only: Credential decryption occurs only on the server during sync or activation operations. Decrypted values are never sent to the browser.
• Credential rotation: To rotate credentials, edit the connection and provide the new credential values. The old encrypted credentials are replaced entirely.

Next Steps

• Sync -- Use an inbound connection to pull topics from an external API
• Segment Activations -- Use an outbound connection to push segments to DSPs
• Data Hygiene -- Monitor the health of your connections and activated segments