---
title: Connect Pipedrive
canonical: "https://agentbarn.dev/guides/integrations/pipedrive"
pubDate: "2026-08-29T00:00:00.000Z"
updatedDate: "2026-09-13T13:41:42.000Z"
author: Agent Barn
description: "Connect Pipedrive to an Agent Barn Agent with an encrypted personal API token, optional company endpoint, isolated Pipedrive Skill, generated profile, and aai-cli CRM access."
tags: [Integrations, How-to, "Pipedrive administrators, Agent operators, and Organization administrators", Pipedrive, CRM, API token, leads, deals, persons, organizations, activities, notes, mailbox, aai-cli, aai-pipedrive, pipedrive-work, company domain, Pipedrive Skill]
categories: [Guides, Integrations]
---

-   Integrations
-   10–15 minutes
-   Requires a Pipedrive personal API token

Connect Pipedrive to let an Agent work with CRM leads, people, organizations, deals, activities, notes, labels, and synced email history.

Agent Barn encrypts the personal API token, and exposes supported operations through the built-in **Pipedrive** Skill and `aai-cli`.

**Security boundary**

A Pipedrive personal API token has no separately selectable scopes. It acts with the permissions and data visibility of its Pipedrive user, and the supported Agent command surface includes create, update, convert, and delete operations. Treat it as a high-privilege secret: store it only through the encrypted Integration credential workflow, never in Skill files, prompts, screenshots, command examples, or source control. Use an account whose access matches the Agent’s responsibility, and restrict Agent instructions when CRM behavior should be read-oriented.

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

| Resource | Read operations | Write operations |
| --- | --- | --- |
| Leads | List, search, get | Create, update, delete, convert to deal |
| Persons | List, search, get, combined view, activities, notes, mail history | Create, update, delete |
| Organizations | List, search, get, combined view, activities, notes, mail history | Create, update, delete |
| Deals | List, search, get, combined view, activities, notes, mail history | Create, update, delete |
| Lead labels | List | Create, update, delete |
| Person labels | List | None |
| Organization labels | List | None |
| Deal labels | List | None |
| Activities | List, get | None |
| Notes | List, get | None |
| Mailbox | Read messages and threads | None |

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.

**Note**

Synced email history is separate from a general email integration. It can only read messages already available through Pipedrive’s email synchronization or Smart BCC features.

## Before you begin

You need:

-   An Agent Barn Organization
-   An existing Agent, or permission to hire one
-   Permission to update the Agent and manage its Secrets
-   A Pipedrive company account
-   A Pipedrive user with access to the intended CRM data
-   Permission to use the Pipedrive API
-   A personal API token for that user and company
-   Optional access to a Pipedrive sandbox for testing write operations

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

Official references:

-   [Find a Pipedrive API token](https://pipedrive.readme.io/docs/how-to-find-the-api-token)
-   [Pipedrive API authentication](https://pipedrive.readme.io/docs/core-api-concepts-authentication)
-   [Enable API access for company users](https://pipedrive.readme.io/docs/enabling-api-for-company-users)
-   [Find the company domain](https://pipedrive.readme.io/docs/how-to-get-the-company-domain)
-   [Pipedrive API reference](https://developers.pipedrive.com/docs/api/v1/)
-   [Pipedrive API rate limits](https://pipedrive.readme.io/docs/core-api-concepts-rate-limiting)

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

| Layer | What it controls |
| --- | --- |
| Pipedrive user permissions | What the API token can read or change |
| Pipedrive visibility | Which CRM records the user can see |
| Agent Barn Agent Access | Which people can operate or configure the Agent |
| Pipedrive Skill | Which Pipedrive commands are documented to the Agent |
| Agent instructions | When the Agent should use read or write commands |

**Important**

Agent instructions are not a provider-enforced security boundary. If a token-owning user can delete a deal, the token may also permit that operation. Restrict the Pipedrive user before relying on prompt instructions.

## Prepare the Pipedrive user

Before copying a token:

1.  Decide whether the Agent should use an existing user, or a dedicated integration user.
2.  Place the user in the narrowest practical Pipedrive permission set.
3.  Limit the user’s data visibility to the records required by the Agent.
4.  Confirm whether the user may create, update, convert, or delete CRM records.
5.  Enable **Use API** for the user’s permission set.
6.  Sign in as that user and confirm the intended CRM records are visible.

If the Agent only needs reporting or research access, remove unnecessary create, update, and delete permissions from the Pipedrive user where the account’s permission model allows it.

**Tip**

Use a Pipedrive developer sandbox or test company when evaluating Agent write behavior. Do not begin write testing against production deals.

## Find the API token

1.  Sign in to Pipedrive as the intended integration user.
2.  Open the account menu.
3.  Open **Company settings**.
4.  Select **Personal preferences**.
5.  Select **API**.
6.  Copy the personal API token.

The token is unique to that user and company.

**Warning**

Pipedrive permits only one active personal API token for a user in a company. Selecting **Generate new token** invalidates the current token, and can immediately break every other integration using it.

If the **API** page is missing, ask a Pipedrive administrator to enable **Use API** for the user’s permission set under **Manage users**.

Do not copy the token into source control, documentation, issues or support tickets, chat messages, Agent prompts, shell history, or screenshots.

## Find the company domain

The company domain is optional in Agent Barn. For this Pipedrive URL:

```
https://acme.pipedrive.com
```

the company domain is `acme`. Enter only the bare subdomain.

### Correct

```
acme
```

### Incorrect

```
https://acme.pipedrive.com
acme.pipedrive.com
https://acme.pipedrive.com/api
```

You can also find the company domain through Pipedrive’s `/users/me` response.

### When to leave the domain empty

Leave **Company domain** empty to use `https://api.pipedrive.com`. The personal token identifies its user and company, so the global endpoint works for ordinary Pipedrive Cloud accounts.

### When to provide the domain

Provide the bare company subdomain when:

-   Your Pipedrive administrator requires tenant-specific routing
-   You are diagnosing a global-endpoint problem
-   Your deployment has been tested against the company-specific hostname

Supplying `acme` produces `https://acme.pipedrive.com`.

**Tip**

Start with the domain empty. Add it only when the tenant-specific endpoint is required.

## Connect Pipedrive

1.  In Agent Barn, open **Agents**.
2.  Select the Agent that needs CRM access.
3.  Open the Agent’s **Configuration**.
4.  Select **Keys & integrations**.
5.  Select **Edit**.
6.  Under **Integration credentials**, add **Pipedrive**.
7.  Select **Manual credential**.
8.  Complete the Pipedrive fields.
9.  Apply the configuration.

| Agent Barn field | Required | Value |
| --- | --- | --- |
| **API token** (`apiToken`) | Yes | Pipedrive personal API token |
| **Company domain** (`domain`) | No | Optional bare Pipedrive company subdomain such as `aai-labs` |

### Global endpoint

```
API token
••••••••••••••••

Company domain
Leave empty
```

### Tenant endpoint

```
API token
••••••••••••••••

Company domain
acme
```

When `domain` is omitted, Agent Barn uses `https://api.pipedrive.com`. When supplied, it uses `https://<domain>.pipedrive.com`; do not enter `https://` or a path. The API token is encrypted and write-only, and Agent Barn never returns the original value.

If the Agent is running, use the website’s restart-aware apply flow. The new credential becomes available after restart.

**Note**

Agent Barn permits one active Pipedrive credential per Agent. Adding another Pipedrive credential replaces the existing one.

## Assign the Pipedrive Skill

The `aai-pipedrive` Skill supplies instructions and command references; the Pipedrive Integration credential supplies authentication. Pipedrive is a tool Integration, not a Communication Connection.

1.  Open the Agent’s **Skills** configuration.
2.  Select **Edit**.
3.  Add the built-in **Pipedrive** Skill.
4.  Apply the change.
5.  Restart the Agent if prompted.

The Skill’s canonical mounted entry point is:

```
./skills/aai-pipedrive/SKILL.md
```

```
aai-pipedrive/
├── SKILL.md
└── references/
    └── command-reference.md
```

Read `./skills/aai-pipedrive/SKILL.md` before using Pipedrive. The command reference belongs to the same isolated bundle, which documents `aai-cli pipedrive`; it is not one file inside a shared `aai-cli` directory. Every command should include `--profile pipedrive-work`.

Assigning the Skill does not create or reveal a credential, adding the credential does not change the Skill, and publishing a newer Skill Version does not repin the Agent. The bundled Skill declares Pipedrive as a required provider, which Agent configuration validates against configured Integration credentials. Pipedrive is not currently a manual-entry Shared Credentials provider.

**Important**

The Agent should use `aai-cli pipedrive`, not direct Pipedrive API calls. It should not ask users to provide an API token through conversation.

## Validate the connection

1.  Return to **Keys & integrations**.
2.  Find the configured Pipedrive credential.
3.  Select **Validate**.
4.  Review the status and identity.

Agent Barn validates the token with the current-user endpoint and the API token. It uses the configured custom company endpoint when `domain` is supplied, otherwise `https://api.pipedrive.com`, and returns the account email or name as the validated identity when available.

### Valid

Pipedrive accepted the token, and the current-user endpoint returned the user’s email or name as the identity.

### Warning

Reserved for providers whose validators report partial results. Personal API tokens have no scopes, so `missing_scopes` stays empty for Pipedrive.

### Invalid

Pipedrive rejected the token, returned a provider error, or the selected endpoint was unreachable. Network reachability errors remain distinct from provider authentication failures.

A successful response resembles:

```
{
  "validation_status": "valid",
  "validation_identity": "agent@example.com",
  "validation_error": null,
  "missing_scopes": []
}
```

An invalid token resembles:

```
{
  "validation_status": "invalid",
  "validation_identity": null,
  "validation_error": "Invalid API token",
  "missing_scopes": []
}
```

Validation confirms that Agent Barn can reach the selected Pipedrive endpoint, that Pipedrive accepts the token, and that the current-user endpoint returns an identity.

Validation does not confirm that the user can see every intended record, that every write operation is permitted, that email synchronization is configured, that the Agent’s operating instructions are safe, or that the company has sufficient API budget for the workflow.

**Important**

Always test a read operation after validation. Authentication success is not authorization coverage.

## Verify Agent access

Begin with read-only commands.

List open deals:

```
aai-cli pipedrive deals list \
  --status open \
  --limit 5 \
  --profile pipedrive-work
```

Search for a person:

```
aai-cli pipedrive persons search \
  --term "Ada" \
  --limit 5 \
  --profile pipedrive-work
```

List recent leads:

```
aai-cli pipedrive leads list \
  --limit 5 \
  --profile pipedrive-work
```

List incomplete activities:

```
aai-cli pipedrive activities list \
  --done false \
  --limit 5 \
  --profile pipedrive-work
```

Read a combined deal view:

```
aai-cli pipedrive deals view 123 \
  --limit 10 \
  --include-labels \
  --profile pipedrive-work
```

Successful responses use Pipedrive’s response envelope:

```
{
  "success": true,
  "data": []
}
```

List responses can also include pagination:

```
{
  "success": true,
  "data": [],
  "additional_data": {
    "pagination": {
      "start": 0,
      "limit": 5,
      "more_items_in_collection": false
    }
  }
}
```

**Tip**

Ask the Agent to identify a known deal or person without changing anything. Confirm that the returned records match the intended Pipedrive visibility boundary.

## Use the supported command groups

```
aai-cli pipedrive leads
aai-cli pipedrive persons
aai-cli pipedrive organizations
aai-cli pipedrive deals
aai-cli pipedrive labels
aai-cli pipedrive activities
aai-cli pipedrive notes
aai-cli pipedrive mailbox
aai-cli pipedrive request
```

Leads support list, search, get, create, update, delete, and conversion. Persons, Organizations, and Deals support list, search, record views, related records, and mutations; deals also expose stage flow. Labels, activities, notes, mailbox data, and uncommon supported endpoints are available through their matching resource groups.

```
aai-cli pipedrive leads list --limit 20 --profile pipedrive-work
aai-cli pipedrive persons search --term "Ada Lovelace" --limit 10 --profile pipedrive-work
aai-cli pipedrive persons view 123 --limit 20 --profile pipedrive-work
aai-cli pipedrive organizations search --term "Acme" --limit 10 --profile pipedrive-work
aai-cli pipedrive deals view 456 --include-mail --limit 20 --profile pipedrive-work
aai-cli pipedrive deals flow 456 --limit 50 --profile pipedrive-work
aai-cli pipedrive activities list --deal-id 456 --limit 20 --profile pipedrive-work
aai-cli pipedrive notes list --deal-id 456 --limit 20 --profile pipedrive-work
aai-cli pipedrive mailbox threads list --folder inbox --limit 20 --profile pipedrive-work
aai-cli pipedrive request get /api/v2/pipelines --profile pipedrive-work
```

**Capability is not Agent policy**

The CLI supports create, update, delete, conversion, labeling, and other writes, but an Agent’s Template and operating instructions may limit it to read-only or confirmation-gated behavior. A command existing does not authorize every Agent to use it.

## Prefer composed views and explicit stage history

Use `deals view`, `persons view`, or `organizations view` when the Agent needs the primary record together with related activities and notes. Add `--include-mail` when synchronized mail is applicable; `mail_messages` appears only when mail inclusion is requested and available.

For deal stage-transition history, use `aai-cli pipedrive deals flow <deal-id> --profile pipedrive-work`. Stage changes are `dealChange` entries whose `field_key` is `stage_id`; a deal’s current `stage_id` is not its complete stage history.

## Interpret response and error shapes

Successful output is JSON on stdout and includes an Agent Barn CLI `_aai` metadata block. Its pagination object can include `continuation`, `has_more`, `instruction`, `next_command`, `returned_count`, and `status`.

```
"_aai": {
  "pagination": {
    "continuation": "…",
    "has_more": false,
    "instruction": "…",
    "next_command": "…",
    "returned_count": 20,
    "status": "complete"
  }
}
```

-   Single-record and mutation commands typically preserve `{ success: true, data: {} }`.
-   List commands typically return `{ success: true, data: [], additional_data: {} }`; older endpoints can use offset pagination and newer v2 endpoints cursors.
-   Search results use `data.items[].item` and `data.items[].result_score`.
-   View commands use a composed `record`, `activities`, `notes`, and optional `mail_messages` shape.

Errors are structured JSON on stderr and exit non-zero. Use safe fields such as `code`, `message`, `operation`, `service`, `status`, and provider details to distinguish `invalid_input`, `config_error`, `auth_error`, `not_found`, `rate_limited`, `provider_api_error`, and `internal_error`. Never copy a token or full secret configuration into logs.

## Control write operations

The Pipedrive Skill includes write commands. Examples include:

```
leads create
leads update
leads delete
leads convert

persons create
persons update
persons delete

organizations create
organizations update
organizations delete

deals create
deals update
deals delete
```

Lead labels also support create, update, and delete.

Before allowing an Agent to write:

1.  Define which record types it may change.
2.  Define whether it may create records.
3.  Define whether it may convert leads.
4.  Define whether it may delete records.
5.  Restrict the Pipedrive user’s permissions where possible.
6.  Add explicit Agent instructions.
7.  Require human confirmation for consequential changes.
8.  Test in a sandbox.

A safe Agent instruction can state:

```
Use Pipedrive read operations without confirmation.

Before creating or updating a CRM record, summarize the intended change and
request confirmation.

Never delete a lead, person, organization, deal, or label.
Never convert a lead unless the user explicitly requests that exact conversion.
```

**Warning**

Avoid testing delete or conversion commands in production. The presence of a command in the Skill does not mean the Agent should use it autonomously.

### Optional sandbox write test

In a Pipedrive sandbox, create a clearly labeled test lead:

```
aai-cli pipedrive leads create \
  --title "Agent Barn integration test" \
  --profile pipedrive-work
```

Inspect the returned lead ID and confirm the record appears in the sandbox. Only remove it if deletion is explicitly authorized:

```
aai-cli pipedrive leads delete LEAD_ID \
  --profile pipedrive-work
```

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

**Important**

Email bodies can contain sensitive personal or commercial information. Grant Agent and log access accordingly.

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

### Without a company domain

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

### With a company domain

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

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

**Important**

A dedicated Pipedrive user limits rotation impact. Reusing a person’s token across unrelated integrations makes safe rotation more difficult.

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

**Security**

To revoke provider access immediately, generate a replacement token in Pipedrive. Remember that this also affects every integration using the old token.

## 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": {
        "apiToken": "REDACTED",
        "domain": ""
      }
    }
  ]
}
```

Using a company-specific endpoint:

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

### Validate the credential

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

```
{
  "validation_status": "valid",
  "validation_identity": "agent@example.com",
  "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

### The Agent cannot use the Pipedrive integration

Check the isolated Skill, profile, and endpoint

Confirm the Pipedrive Integration is configured, the `aai-pipedrive` Skill is assigned and published, then read `./skills/aai-pipedrive/SKILL.md`. Pass `--profile pipedrive-work`, confirm the personal API token remains valid, and ensure an optional company domain is only the intended bare subdomain. Remove the optional domain to use `https://api.pipedrive.com` when a custom endpoint is unnecessary. Use structured stderr to distinguish authentication, rate-limit, provider, and network failures.

### The API page is missing in Pipedrive

Use API is not enabled

The user’s permission set may not allow API use. Ask a Pipedrive administrator to enable **Use API** under:

```
Manage users → Permission sets
```

### Validation reports “Invalid API token”

Token replaced, disabled, or wrong type

Check that:

-   The token was copied completely
-   It belongs to the intended user and company
-   Another integration or administrator did not generate a replacement token
-   API access remains enabled for the user
-   You did not paste an OAuth access token

Copy the current token from the user’s Pipedrive API settings.

### Validation succeeds but records are missing

Visibility, not authentication

Validation only checks the current user endpoint. Check the token-owning user’s:

-   Company membership
-   Permission set
-   Record visibility
-   Team or ownership restrictions
-   Access to archived or deleted records
-   Filters supplied to the command

### The company-domain endpoint fails

Use the bare subdomain

Confirm that **Company domain** contains only the bare subdomain. For `https://acme.pipedrive.com`, enter `acme`.

If tenant-specific routing is unnecessary, clear the field to use `https://api.pipedrive.com`.

### Read commands work but write commands fail

The user lacks the permission

The Pipedrive user may lack permission for the requested operation. Check:

-   The user’s permission set
-   Whether the record is visible and editable
-   Required Pipedrive fields
-   Pipeline or stage restrictions
-   Whether the record was already deleted or converted

Do not broaden the user’s permissions without reviewing the Agent’s intended responsibilities.

### Mailbox commands return no data

Email sync or message permissions

Check that:

-   Email synchronization or Smart BCC is configured in Pipedrive
-   The token-owning user has permission to view the messages
-   The requested folder contains synced threads
-   The CRM record is associated with the expected email message
-   The account plan supports the required email feature

### \--include-mail fails

The record is visible; its mail is not

The base person, organization, or deal may be accessible while its associated email history is not.

Retry without `--include-mail`. Then review email synchronization and mailbox permissions separately.

### Commands return HTTP 429

Budget or burst limit reached

Stop automatic retries, reduce request frequency, lower list limits, and review the Pipedrive API Usage Dashboard.

### A token rotation broke another integration

One active token per user and company

Pipedrive permits one active personal API token per user and company. Generating a new token invalidates the previous one.

Update every authorized integration that used the old token, or move Agent Barn to a dedicated Pipedrive user.

### The credential cannot be removed

A Skill still requires it

A remaining assigned Skill requires Pipedrive. Remove the Pipedrive Skill before removing the credential.

### Updated credentials are not being used

Artifacts are produced at startup

Restart the Agent. Encrypted runtime Secrets, the `pipedrive-work` profile, mounted Skills, and generated tool context are created during startup.

## 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 Firecrawl** The next integration in this section](/guides/integrations/firecrawl) [**Manage Agent credentials** Credential classes, validation, and boundaries](/guides/integrations/credentials) [**Work with Skills** How Skills package provider workflows](/guides/templates-and-skills/skills)

-   [Connect Zoho](/guides/integrations/zoho)
-   [Review Agent health and logs](/guides/agents/health-and-logs)
-   [Manage Skill Versions](/guides/templates-and-skills/skill-versions)
-   [Configure an Agent](/guides/agents/configuration)
