> ## Documentation Index
> Fetch the complete documentation index at: https://support.affinity.co/llms.txt
> Use this file to discover all available pages before exploring further.

# How to securely set up third-party integrations

> Workflow recipe: How to securely set up third-party integrations

<Note>**How-to** — task-oriented recipe.</Note>

**Last Updated:** November 21, 2025

**Object Tags:** Integrations, API Keys, Security, Third-Party, Data Integration, Setup

***

## Overview

Safely connect third-party tools and platforms to your Affinity CRM using proper API key management practices. This workflow ensures integrations are documented, secured, and maintainable while minimizing security risks and enabling future auditability.

**What you'll accomplish:** Set up external integrations (data warehouses, reporting tools, marketing platforms) with properly created and documented API keys, secure credential handling, and clear ownership.

**Who it's for:** IT teams, data engineers, operations managers, admins setting up integrations with Salesforce, Snowflake, Looker, or custom tools.

**When to use this:** Setting up new data warehouse connections, third-party reporting tools, marketing automation integrations, or custom applications accessing Affinity data.

***

## Prerequisites

* "Generate API Key" permission (to create keys)
* OR request admin to create key on your behalf
* Understanding of integration requirements (read-only vs read-write, data scope)
* Secure credential storage system available
* Integration platform/tool ready to configure

***

## Workflow Steps

### Step 1: Plan the Integration

**Define requirements:**

1. **What data is needed?**

* Companies, People, Opportunities, Lists?
  * Specific fields or all fields?
  * Historical data or incremental updates?

1. **What access level?**

* Read-only (most third-party tools)
  * Read-write (bi-directional syncs like Salesforce)

1. **What's the frequency?**

* Real-time via webhooks
  * Scheduled (hourly, daily, weekly)
  * On-demand/manual

1. **Who owns this integration?**

* Which team/person is responsible?
  * Who to contact if it breaks?
  * Where is it documented?
    **Get approval if required:**

* Check with IT security/compliance team

* Verify integration aligns with data policies

* Document approval in integration request

### Step 2: Create Properly Documented API Key

**Navigate to Manage Apps:**

1. Settings > Manage Apps
2. Click "Create New API Key"
   **Name the key descriptively:**

**Use clear naming pattern:**

* **System-based**: "\[Tool Name] Integration"
* Examples: "Snowflake Data Sync", "Looker Reporting", "Salesforce Bi-Sync"
* **Purpose-based**: "\[Purpose] API Key"
* Examples: "Executive Dashboard API", "Marketing Automation Key"
  **Add comprehensive description:**

**Template:**

```javascript theme={null}
Purpose: [What this integration does]
Owner: [Team or person responsible]
Contact: [Email for questions]
Systems: [Which external system(s) connect]
Frequency: [How often it runs]
Access: [Read-only or Read-write]
Approved by: [Who approved this integration]
Created: [Date]
```

**Example:**

```javascript theme={null}
Purpose: Syncs Affinity opportunities to Snowflake for executive reporting
Owner: Data Engineering team
Contact: data-team@company.com
Systems: Snowflake data warehouse, dbt transformations, Looker dashboards
Frequency: Nightly at 2 AM UTC via Airflow
Access: Read-only
Approved by: CTO (10/15/2025)
Created: 11/21/2025
```

**Click Create:**

1. API key secret appears (shown only once)
2. **Immediately copy the secret**
3. Do not close modal until secret is safely stored

### Step 3: Store Secret Securely

**Choose secure storage:**

**For production integrations:**

1. **Secrets management system** (preferred):

* AWS Secrets Manager
  * HashiCorp Vault
  * Azure Key Vault
  * Google Cloud Secret Manager

1.

**CI/CD environment variables**:

* GitHub Secrets
  * GitLab CI Variables
  * CircleCI Environment Variables
    **For user/team access:**

1.

**Password manager**:

* 1Password (team vault)
  * LastPass (shared folders)
  * Bitwarden (organization vault)
    **Never store in:**

* ❌ Code repositories (even private)

* ❌ Slack messages or email

* ❌ Unencrypted documents

* ❌ Browser bookmarks or notes

* ❌ Shared spreadsheets
  **Document storage location:**

* Add to key description: "Secret stored in 1Password Engineering vault"

* Include in team wiki integration documentation

* Ensure backup access if primary owner unavailable

### Step 4: Configure the Integration

**In your third-party tool:**

**Common setup patterns:**

**For data warehouses (Snowflake, BigQuery, Redshift):**

1. Configure data pipeline tool (Fivetran, Airbyte, custom ETL)

2. Add Affinity API key to connector configuration

3. Set up API endpoint URLs (v1 or v2)

4. Configure sync frequency and tables

5. Test connection and initial data pull
   **For reporting tools (Looker, Tableau, Power BI):**

6. Set up data source connection

7. Add API authentication with your key

8. Configure data refresh schedule

9. Test queries and verify data loads
   **For CRM sync (Salesforce, HubSpot):**

10. Install integration connector or middleware

11. Add Affinity API credentials

12. Map fields between systems

13. Configure sync direction (one-way or bi-directional)

14. Set sync frequency

15. Run initial test sync
    **For custom applications:**

16. Add API key to application configuration

17. Implement proper error handling for API failures

18. Add logging for API requests

19. Test all API endpoints needed

20. Implement rate limiting handling

### Step 5: Test the Integration

**Validation checklist:**

1.

**Connectivity test**:

* Can system authenticate with API?
  * Are requests succeeding?
  * Check for authentication errors

1.

**Data validation**:

* Is correct data flowing?
  * Are all required fields present?
  * Check data accuracy against Affinity

1.

**Performance**:

* Is sync completing in expected timeframe?
  * Check API usage in Manage Apps
  * Verify not approaching rate limits

1.

**Error handling**:

* What happens if API key is revoked?
  * Are errors logged appropriately?
  * Is there alerting for failures?

1.

**Documentation**:

* Is integration documented in wiki?
  * Can someone else maintain this?
  * Are credentials location noted?

### Step 6: Monitor and Maintain

**Ongoing maintenance:**

**Weekly:**

* Check integration is running successfully

* Verify data sync is current

* Review any error logs
  **Monthly:**

* Verify API usage is stable

* Check key "Last Used" in Manage Apps

* Ensure integration still meets business needs
  **Quarterly:**

* Review key description - is it still accurate?

* Verify owner is still correct contact

* Check if integration documentation needs updates

* Participate in org-wide API key audit
  **When issues arise:**

1. Check Manage Apps for key status (Active vs Revoked)
2. Verify API usage hasn't hit limits
3. Check integration error logs
4. Contact Affinity support if API issues suspected

### Step 7: Plan for Key Rotation (When Needed)

**When to rotate:**

* Annual security policy requirement
* Team member with key access left company
* Suspected key exposure
* Integration ownership changing
* Upgrading to M4 with multiple keys per user
  **Current rotation process (M3):**

1.

**Plan downtime window**:

* Integration will break briefly during rotation
  * Schedule during low-usage period
  * Notify stakeholders

1.

**Create new key**:

* Create in Manage Apps (revokes old key automatically)
  * Copy new secret immediately
  * Store in secrets management system

1.

**Update integration**:

* Replace old secret with new secret in configuration
  * Deploy configuration change
  * Test connection

1.

**Verify**:

* Integration working with new key
  * Old key shows "Revoked" in Manage Apps
  * New key shows recent "Last Used"
    **Future rotation (M4+):**

* Create new key while keeping old key active

* Update integration to use new key

* Test thoroughly

* Revoke old key after confirming new key works

* Zero-downtime rotation

***

## Expected Outcome

* Third-party integration successfully connected to Affinity
* API key properly documented with name, description, and purpose
* Secret stored securely in approved credential management system
* Integration running reliably with appropriate monitoring
* Clear ownership and maintenance responsibility established
* Easy audit trail for security and compliance teams
* Knowledge transfer possible if owner changes

***

## Tips & Best Practices

**Pre-Integration:**

* **Get security approval** before creating keys for third-party tools

* **Verify vendor security** - is third-party tool trustworthy?

* **Check data residency** - where will your Affinity data be stored?

* **Review terms** - does integration vendor meet your compliance needs?
  **Secret Handling:**

* **Copy secret immediately** - shown only once at creation

* **Test secret** before closing creation modal

* **Store in approved system** per InfoSec policy

* **Never share** via insecure channels

* **Rotate annually** or per security policy
  **Documentation:**

* **Name + Description mandatory** - make it a standard

* **Include contact info** so others can ask questions

* **Link to integration docs** in description if possible

* **Update when changes made** to integration
  **Testing:**

* **Test in non-production first** if possible

* **Verify data accuracy** before trusting integration

* **Monitor initially closely** (daily for first week)

* **Set up alerts** for integration failures
  **Monitoring:**

* **Check "Last Used" monthly** to verify health

* **Monitor API usage** to avoid hitting limits

* **Review error logs** in your integration platform

* **Audit permissions** if integration behavior changes
  **Common Integration Types:**

**Data Warehouses:** Usually read-only, scheduled sync, high volume

**Reporting Tools:** Read-only, moderate frequency, specific fields

**CRM Sync:** Read-write, real-time or frequent, bi-directional

**Marketing Automation:** Read-only, scheduled, specific segments

**Custom Dashboards:** Read-only, real-time or cached, focused queries

***

## Example Use Case

TechVentures needs to connect Affinity to their Snowflake data warehouse for executive reporting:

**Requirements:**

* Pull all companies, opportunities, and interactions
* Nightly sync to data warehouse
* Read-only access (no writing back to Affinity)
* Dashboard in Looker built on warehouse data
  **Day 1 - Planning:**

1. Data Engineer Sarah reviews Affinity API documentation

2. Confirms needed endpoints: Companies, Opportunities, Lists, Field Values

3. Gets approval from CTO and InfoSec team

4. Documents plan in team wiki
   **Day 2 - Key Creation:**

5. Sarah navigates to Settings > Manage Apps

6. Clicks "Create New API Key"

7.

**Name**: "Snowflake Data Warehouse Sync"
4\.

**Description**: "Nightly sync of Affinity CRM data to Snowflake for executive dashboards. Owner: Data Engineering ([data@techventures.com](mailto:data@techventures.com)). Systems: Snowflake, Airbyte, Looker. Frequency: Daily 2 AM UTC. Access: Read-only. Approved by CTO 11/15/2025. Secret stored in AWS Secrets Manager."
5\. Creates key
6\. Immediately copies secret
7\. Stores in AWS Secrets Manager under key name "affinity/snowflake-etl"
8\. Documents secret location in team wiki
**Day 3 - Integration Configuration:**

1. Configures Airbyte connector for Affinity

2. Adds API key from AWS Secrets Manager

3. Selects API v2 endpoints

4. Maps Affinity objects to Snowflake tables

5. Sets sync schedule: Daily 2 AM UTC

6. Runs initial test sync (manual)
   **Day 4 - Testing:**

7. Verifies 500 companies synced successfully

8. Spot-checks data accuracy (10 random records match)

9. Confirms all required fields present

10. Checks Manage Apps: "Last Used" shows recent timestamp

11. Checks API usage: 2,450 requests used (well under limit)
    **Day 5 - Monitoring Setup:**

12. Configures Airbyte failure alerts (email + Slack)

13. Sets up daily Snowflake freshness check

14. Creates Looker dashboard showing sync status

15. Adds integration to team's operational documentation
    **Week 2 - Production:**

16. Enables automated nightly sync

17. Monitors daily for first week

18. Everything running smoothly

19. Executives now have accurate CRM dashboards
    **Month 1 - Review:**

20. Sarah checks Manage Apps:

* Key shows "Last Used" daily
  * API usage stable at \~2.5k requests/day
  * Well under monthly limit

1. Integration documented in quarterly InfoSec audit

2. Zero issues or downtime
   **Month 3 - Ownership Transfer:**

3. Sarah leaving for new role

4. Transfers integration ownership to teammate Mike

5. Updates key description:

* Changes contact from sarah@ to mike@
  * Notes ownership transfer date

1. Mike verified access to AWS Secrets Manager

2. Seamless transition (key still works, no recreation needed)
   **Month 12 - Annual Rotation:**

3. Security policy requires annual key rotation

4. **Current process** (until M4):

* Plans Saturday 2 AM rotation (low usage time)
  * Creates new key (old revokes automatically)
  * Updates Airbyte configuration immediately
  * Tests sync
  * 15-minute downtime window

1. **With M4** (when available):

* Creates second key while first active
  * Updates Airbyte to new key
  * Tests thoroughly
  * Revokes old key after verification
  * Zero downtime
    **Result:** Successful, secure, maintainable integration with full audit trail and minimal operational overhead.

***

## Expected Outcome

* Third-party tool successfully connected to Affinity API
* Data flowing reliably on expected schedule
* API key fully documented with purpose and ownership
* Secret stored securely per InfoSec requirements
* Monitoring and alerting in place for failures
* Integration documented in team wiki
* Clear ownership and contact information for maintenance
* Passes security audit requirements

***

## Tips & Best Practices

**Planning Phase:**

* **Start with read-only** unless write access absolutely necessary

* **Minimize data scope** - only pull fields you need

* **Understand rate limits** - plan sync frequency accordingly

* **Review vendor security** - is third-party tool trustworthy?
  **Key Creation:**

* **Descriptive names** prevent "What is this?" questions later

* **Rich descriptions** enable knowledge transfer

* **Include contacts** so others can ask questions

* **Note approval** for audit trail
  **Secret Handling:**

* **Use secrets manager** for production integrations

* **Password manager** acceptable for user-level integrations

* **Document storage location** in key description

* **Never commit to git** - use environment variables

* **Rotate annually** or per policy
  **Testing:**

* **Test in sandbox first** if available

* **Start with small data set** before full sync

* **Verify data accuracy** - spot check records

* **Monitor API usage** during initial loads

* **Set up alerting** before going to production
  **Common Third-Party Tools:**

**Data Warehouses:**

* Snowflake, BigQuery, Redshift

* Use ETL tools: Fivetran, Airbyte, dbt

* Read-only access sufficient

* Schedule overnight syncs
  **Reporting/BI:**

* Looker, Tableau, Power BI

* Read-only access

* Can query API directly or via warehouse

* Consider caching for performance
  **CRM Sync:**

* Salesforce, HubSpot, Pipedrive

* May need read-write for bi-directional

* Real-time or frequent syncs

* Field mapping critical
  **Marketing Tools:**

* Marketo, Pardot, MailChimp

* Read-only (pull contact lists)

* Scheduled syncs

* Privacy compliance important
  **Troubleshooting Integration Issues:**

**Key revoked accidentally:**

* Create new key with same documentation

* Update integration immediately

* Test connection

* Minimize downtime
  **Hitting rate limits:**

* Check Manage Apps for current usage

* Reduce sync frequency

* Batch requests more efficiently

* Contact Affinity for limit increase if needed
  **Authentication failures:**

* Verify key is still Active in Manage Apps

* Check secret matches what's configured

* Ensure user who created key still active

* Verify API endpoint URLs are correct

***

## Example Use Case

Velocity Capital Partners needed to sync Affinity data with their internal reporting stack:

**Their Tech Stack:**

* Affinity (CRM)
* Snowflake (Data Warehouse)
* dbt (Transformations)
* Looker (Dashboards)
* Airflow (Orchestration)
  **The Integration:**

**Month 1 - Planning:**

1. Data team identified need for executive KPI dashboard

2. Required data: Companies, Opportunities, Interactions, Lists

3. Got approval from CTO and InfoSec

4. Selected Airbyte for ETL (native Affinity connector)
   **Month 1 Week 2 - Setup:**

5. Created API key:

* Name: "Snowflake Executive Dashboard Sync"
  * Description: Full details (purpose, owner, systems, schedule, approval)

1. Stored secret in AWS Secrets Manager
2. Configured Airbyte:

* Affinity source with API key from Secrets Manager
  * Snowflake destination
  * Selected all needed endpoints
  * Scheduled: Nightly 2 AM UTC

1. Ran initial full sync: 10,000 companies, 2,500 opportunities

2. Verified data in Snowflake matched Affinity
   **Month 1 Week 3 - Production:**

3. Enabled automated nightly sync

4. Built dbt transformations on raw data

5. Created Looker dashboards

6. Presented to executives - big win!
   **Month 6 - Expansion:**

7. Business team wanted CRM sync to Salesforce too

8. Created second API key:

* Name: "Salesforce Bi-Directional Sync"
  * Description: Different purpose, different owner (RevOps)

1.

**Problem**: Hit 1 key per user limit (M3)
2\.

**Solution**: Had RevOps team member create key under their account
3\.

**Note**: After M4, Data Engineer can have both keys
**Month 12 - Annual Audit:**

1. Security audit required reviewing all API integrations
2. Manage Apps provided instant inventory:

* 2 keys clearly documented
  * Both actively used (Last Used \< 24 hours)
  * Owners current and responsive
  * Secrets stored per policy (AWS Secrets Manager)

1. Passed audit with zero findings

## Result

* Executive team has real-time CRM dashboards
* RevOps has bi-directional Salesforce sync
* Both integrations documented and compliant
* Zero security incidents
* Zero unplanned downtime
* Easy audit compliance

***