How to securely set up third-party integrations

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.

​

Overview

​

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

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

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

• 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:

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]

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

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

1. Secrets management system (preferred):

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

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

• 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

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

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

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

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

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

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

​

Step 6: Monitor and Maintain

• 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)

• 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):

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

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

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

• 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

• 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:

​

Example Use Case

• 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”

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

• 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:

• 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:

• 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

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

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. 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