Connect Pipedrive

What you will configure

1. Pipedrive company
2. Dedicated user
3. Personal API token
4. Encrypted Agent Secret
5. pipedrive-work profile

Pipedrive company
        │
        ▼
Dedicated Pipedrive user
        │
        ├── Permission set
        ├── Data visibility
        └── Personal API token
                  │
                  ▼
       Encrypted Agent Secret
                  │
                  ▼
        Built-in Pipedrive Skill
                  │
                  ▼
         pipedrive-work profile
                  │
                  ▼
          aai-cli pipedrive

At the end of this guide, the Agent will have:

• An encrypted pipedrive credential
• The built-in Pipedrive Skill
• A generated pipedrive-work profile
• Access to CRM data visible to the token-owning Pipedrive user
• Read and write commands for supported Pipedrive resources

Supported operations

The current Pipedrive Skill exposes these operations.

The Skill does not expose every endpoint in the Pipedrive API. It provides the command surface documented above, and the token may allow more Pipedrive API operations than the Skill exposes.

Before you begin

For production use, create a dedicated Pipedrive integration user where your plan and account structure allow it.

Official references:

• Find a Pipedrive API token
• Pipedrive API authentication
• Enable API access for company users
• Find the company domain
• Pipedrive API reference
• Pipedrive API rate limits

Understand the access boundary

A personal API token is tied to:

One Pipedrive user
        +
One Pipedrive company

A user has a different token for each company they belong to. The effective Agent boundary is the combination of these layers:

1. Pipedrive user permissions Permission set, item visibility, and company membership
2. Personal API token Inherits the user’s permissions — it has no scopes of its own
3. Agent Barn Agent access Who may operate or configure the Agent
4. Pipedrive Skill Which Pipedrive commands are documented to the Agent
5. Agent instructions When the Agent should use read or write commands

Access synced email history

Mailbox commands require Pipedrive email synchronization or Smart BCC data. The token-owning user must have permission to view the relevant messages.

Supported commands include:

aai-cli pipedrive mailbox threads list \
  --folder inbox \
  --limit 10 \
  --profile pipedrive-work

aai-cli pipedrive mailbox threads get THREAD_ID \
  --profile pipedrive-work

aai-cli pipedrive mailbox threads messages THREAD_ID \
  --profile pipedrive-work

aai-cli pipedrive mailbox messages get MESSAGE_ID \
  --include-body \
  --profile pipedrive-work

Associated email history can also be added to combined views:

aai-cli pipedrive deals view DEAL_ID \
  --include-mail \
  --limit 10 \
  --profile pipedrive-work

The current Skill does not send email or modify mailbox threads.

Runtime behavior

When the Agent starts, Agent Barn:

1. Decrypts the Pipedrive credential.
2. Stores the token in the encrypted aai-cli secret store.
3. Generates the pipedrive-work profile.
4. Mounts the Pipedrive Skill.
5. Adds Pipedrive to the Agent’s configured integration context.

[profiles.pipedrive-work]
auth_type = "pipedrive_personal_token"
api_token_secret = "pipedrive.api_token"

[profiles.pipedrive-work]
auth_type = "pipedrive_personal_token"
base_url = "https://acme.pipedrive.com"
api_token_secret = "pipedrive.api_token"

The token itself is not written into the profile. The profile references pipedrive.api_token.

The complete runtime path is:

Encrypted Pipedrive token
           │
           ▼
      Agent start
           │
           ├── Encrypted aai-cli secret
           ├── pipedrive-work profile
           └── Pipedrive Skill
                       │
                       ▼
              aai-cli pipedrive
                       │
                       ▼
                 Pipedrive API

Credential changes take effect after the Agent restarts.

Use a Shared Credential

Pipedrive supports Organization-owned Shared Credentials. Use one when:

• Multiple Agents should act as the same Pipedrive user
• An Organization administrator should own token rotation
• Individual Agent operators should not handle the token
• The same company and Pipedrive permission boundary applies to several Agents

To attach one:

1. Create or locate the Pipedrive Shared Credential in the Organization.
2. Open the Agent’s Keys & integrations configuration.
3. Add Pipedrive.
4. Switch from Manual credential to Shared Credential.
5. Select the intended credential.
6. Apply the change.
7. Restart the Agent if prompted.
8. Validate and run a read-only command.

An Agent can use either a manual Pipedrive credential or a Shared Pipedrive Credential, not both simultaneously.

Use separate Shared Credentials when Agents require different Pipedrive users, companies, visibility, or operational risk boundaries. Continue to Use shared credentials for the complete ownership model.

Rotate or remove the credential

Rotate the personal API token

Pipedrive allows one active personal API token per user and company. Before rotation:

1. Inventory every integration using the current token.
2. Schedule a short migration window.
3. Open the user’s Personal preferences → API page.
4. Generate a new token.
5. Immediately replace the token in Agent Barn.
6. Restart affected Agents.
7. Validate the credential.
8. Run a read-only CRM command.
9. Update any other authorized integrations that shared the old token.

Generating the new token invalidates the old one.

Rotate a Shared Credential

Update the Organization-owned Shared Credential, validate it, and restart every attached Agent that must receive the regenerated runtime Secret.

Remove the credential

Before removal:

1. Remove or replace any assigned Skill that requires Pipedrive.
2. Stop the Agent, or use the website’s restart-aware apply flow.
3. Open Keys & integrations.
4. Mark the Pipedrive credential for removal.
5. Apply the change.
6. Restart and verify the Agent.

Agent Barn blocks removal while an assigned Skill still requires the pipedrive provider.

API reference

Add or replace a manual credential

The Agent must be stopped when using the raw update endpoint.

PATCH /api/v1/organizations/{organization_id}/agents/{agent_id}
Content-Type: application/json

Using the global endpoint:

{
  "secrets": [
    {
      "provider": "pipedrive",
      "content": {
        "api_token": "REDACTED",
        "domain": ""
      }
    }
  ]
}

Using a company-specific endpoint:

{
  "secrets": [
    {
      "provider": "pipedrive",
      "content": {
        "api_token": "REDACTED",
        "domain": "acme"
      }
    }
  ]
}

Attach a Shared Credential

{
  "shared_credentials": [
    {
      "shared_credential_id": "00000000-0000-0000-0000-000000000000"
    }
  ]
}

Validate the credential

POST /api/v1/organizations/{organization_id}/agents/{agent_id}/integrations/pipedrive/validate

{
  "validation_status": "valid",
  "validation_identity": "[email protected]",
  "validation_error": null,
  "missing_scopes": []
}

Remove the credential

{
  "removed_secret_providers": [
    "pipedrive"
  ]
}

Credential operations require access to the Agent and the relevant update and secret-management permissions, including agent.secret.manage.

Rate limits

Pipedrive uses token-based API budgets and burst limits. Important characteristics include:

• API calls consume different numbers of budget tokens
• List and search operations can cost more than single-record reads
• The daily budget is shared at the Pipedrive company level
• Burst limits apply per API token
• A depleted budget can produce HTTP 429
• Continued high-volume traffic after rate-limit responses can result in temporary blocking

Reduce avoidable usage by:

• Using narrow list limits
• Applying server-side filters
• Avoiding repeated full-record scans
• Caching stable identifiers in an approved workflow
• Stopping retries after a rate-limit error
• Spacing scheduled Agent jobs
• Monitoring the company’s API Usage Dashboard

Troubleshooting

Manage users → Permission sets

Security practices

• Use a dedicated Pipedrive integration user where possible
• Restrict that user’s permission set
• Restrict record visibility
• Do not treat Agent instructions as the only write boundary
• Require confirmation for consequential CRM writes
• Prohibit deletion unless explicitly needed
• Test write workflows in a sandbox
• Use separate credentials for separate companies or authorization boundaries
• Prefer Shared Credentials when administrators should own rotation
• Do not reuse the token across unrelated integrations
• Keep the token out of source control, logs, screenshots, and conversations
• Validate after every credential change
• Run a real read operation after validation
• Monitor API usage and rate-limit errors
• Review Agent activity and logs for unexpected CRM mutations

Next steps

• Connect Zoho
• Review Agent health and logs