Pieces Management - Activepieces

Pieces are integrations in Activepieces. Platform and project administrators can control which pieces are available to users through filtering and private registries.

Overview

Activepieces provides three levels of piece filtering:

Platform Level

Global piece filtering for entire platform

Project Level

Per-project piece restrictions

Private Registry

Custom piece deployment

Platform Piece Filtering

Control which pieces are available across your platform:

Filter Behaviors

Allowed (Whitelist)
Blocked (Blacklist)

Allow Specific Pieces

Only specified pieces are available:

{
  filteredPieceBehavior: FilteredPieceBehavior.ALLOWED,
  filteredPieceNames: [
    "@activepieces/piece-slack",
    "@activepieces/piece-gmail",
    "@activepieces/piece-google-sheets",
    "@activepieces/piece-hubspot"
  ]
}

Use Cases:

Security compliance requirements
Limiting integrations to approved vendors
Controlling data flow to specific services

Block Specific Pieces

All pieces available except blocked ones:

{
  filteredPieceBehavior: FilteredPieceBehavior.BLOCKED,
  filteredPieceNames: [
    "@activepieces/piece-dropbox",
    "@activepieces/piece-box"
  ]
}

Use Cases:

Blocking competing services
Preventing data exfiltration to specific vendors
Regulatory compliance

Platform filtering is deprecated in favor of project-level filtering, which provides more granular control.

Project Piece Plans

Configure piece availability per project for fine-grained control:

Creating a Project Plan

{
  projectId: "proj_abc123",
  name: "Enterprise Security Plan",
  piecesFilterType: PiecesFilterType.ALLOWED,
  pieces: [
    "@activepieces/piece-slack",
    "@activepieces/piece-microsoft-teams",
    "@activepieces/piece-salesforce"
  ],
  locked: false
}

Filter Types

NONE
ALLOWED

No Filtering (Default)

All platform pieces are available:

{
  piecesFilterType: PiecesFilterType.NONE,
  pieces: []  // Empty array
}

Best for:

Development environments
Unrestricted projects
Maximum flexibility

Allowlist Mode

Only specified pieces are available:

{
  piecesFilterType: PiecesFilterType.ALLOWED,
  pieces: [
    "@activepieces/piece-http",
    "@activepieces/piece-data-mapper",
    "@activepieces/piece-slack"
  ]
}

Best for:

Production environments
Compliance requirements
Customer-specific integrations

Plan Locking

Lock plans to prevent modifications:

{
  locked: true  // Plan cannot be changed
}

Locked plans ensure compliance policies cannot be bypassed by project administrators.

Installing Pieces

Community Pieces

Activepieces includes 200+ community pieces:

Browse Available Pieces

View all pieces in the piece marketplace:

GET /v1/pieces

Check Piece Availability

Pieces are automatically available based on filtering rules

Use in Flows

Add pieces to flows through the flow builder

Private Pieces

Deploy custom pieces to your platform:

Build Custom Piece

Create piece using the Activepieces CLI:

npx @activepieces/cli create-piece my-custom-piece

Publish to Registry

npx @activepieces/cli publish-piece \
  --path ./my-custom-piece \
  --registry https://your-registry.com

Configure Platform

Point platform to your private registry:

AP_PIECES_SOURCE=PRIVATE
AP_PRIVATE_PIECES_REGISTRY=https://your-registry.com

Piece Filtering Logic

The system applies filters in this order:

Filtering Rules

Platform Filter

If platform has ALLOWED behavior:

Only pieces in filteredPieceNames are included

If platform has BLOCKED behavior:

All pieces except those in filteredPieceNames

Project Filter

If project has ALLOWED filter:

Only pieces in project plan’s pieces array

If project has NONE filter:

All pieces from platform filter

Hidden Pieces

If includeHidden=true:

All filters bypassed (admin view)

Managing Piece Allowlists

Adding Pieces to Allowlist

curl -X PATCH 'https://api.activepieces.com/v1/platforms/{platformId}' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "filteredPieceBehavior": "ALLOWED",
    "filteredPieceNames": [
      "@activepieces/piece-slack",
      "@activepieces/piece-gmail"
    ]
  }'

curl -X PATCH 'https://api.activepieces.com/v1/project-plans/{planId}' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "piecesFilterType": "ALLOWED",
    "pieces": [
      "@activepieces/piece-http",
      "@activepieces/piece-slack"
    ]
  }'

Common Piece Combinations

Essential Workflow Pieces

[
  "@activepieces/piece-http",
  "@activepieces/piece-data-mapper",
  "@activepieces/piece-webhook",
  "@activepieces/piece-delay",
  "@activepieces/piece-date-helper",
  "@activepieces/piece-text-helper"
]

Business Communication

[
  "@activepieces/piece-slack",
  "@activepieces/piece-microsoft-teams",
  "@activepieces/piece-gmail",
  "@activepieces/piece-smtp"
]

CRM & Sales

[
  "@activepieces/piece-salesforce",
  "@activepieces/piece-hubspot",
  "@activepieces/piece-pipedrive",
  "@activepieces/piece-zoho-crm"
]

Data & Storage

[
  "@activepieces/piece-google-sheets",
  "@activepieces/piece-airtable",
  "@activepieces/piece-postgresql",
  "@activepieces/piece-mysql",
  "@activepieces/piece-mongodb"
]

Private Piece Registry

Host your own piece registry for custom integrations:

Registry Setup

Choose Registry Type

Options:

npm private registry
Verdaccio
Artifactory
GitHub Packages

Configure Environment

# Use private registry
AP_PIECES_SOURCE=PRIVATE
AP_PRIVATE_PIECES_REGISTRY=https://registry.company.com

# Authentication (if required)
NPM_TOKEN=your-token-here

Publish Custom Pieces

cd my-custom-piece
npm publish --registry https://registry.company.com

Registry Configuration

// .npmrc for custom registry
registry=https://registry.company.com
//registry.company.com/:_authToken=${NPM_TOKEN}

Piece Metadata

Each piece has metadata that affects filtering:

{
  name: "@activepieces/piece-slack",
  displayName: "Slack",
  version: "0.9.0",
  minimumSupportedRelease: "0.20.0",
  maximumSupportedRelease: "999.0.0",
  auth: { type: "OAUTH2" },
  actions: [...],
  triggers: [...]
}

Hidden Pieces

Some pieces are hidden from normal users:

const isHidden = piece.name.startsWith('@activepieces/piece-internal-')

Checking Piece Availability

Verify if a piece is available to a project:

const isFiltered = await enterpriseFilteringUtils.isFiltered({
  piece: pieceMetadata,
  projectId: "proj_abc123",
  platformId: "platform_123"
})

if (isFiltered) {
  throw new Error('Piece not available in this project')
}

Use Cases

Multi-Tenant SaaS

Scenario: Offer different piece sets per pricing tierImplementation:

Free tier: Core pieces only
Pro tier: + Business integrations
Enterprise: All pieces + custom pieces

const freeTierPlan = {
  piecesFilterType: PiecesFilterType.ALLOWED,
  pieces: ['@activepieces/piece-http', '@activepieces/piece-webhook']
}

Security Compliance

Scenario: Restrict data flow to approved vendors onlyImplementation: Block all pieces, then allowlist approved ones:

{
  piecesFilterType: PiecesFilterType.ALLOWED,
  pieces: approvedVendorPieces,
  locked: true  // Prevent changes
}

Custom Integrations

Scenario: Provide internal system integrationsImplementation:

Deploy private pieces to custom registry
Make available only to specific projects

{
  pieces: [
    '@company/piece-internal-crm',
    '@company/piece-erp-system'
  ]
}

Regional Restrictions

Scenario: Comply with data residency lawsImplementation: Block pieces that transfer data outside region:

{
  filteredPieceBehavior: FilteredPieceBehavior.BLOCKED,
  filteredPieceNames: nonCompliantPieces
}

API Reference

curl -X GET 'https://api.activepieces.com/v1/pieces?projectId={projectId}' \
  -H 'Authorization: Bearer {token}'

curl -X GET 'https://api.activepieces.com/v1/pieces/{pieceName}' \
  -H 'Authorization: Bearer {token}'

curl -X PATCH 'https://api.activepieces.com/v1/project-plans/{planId}' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "pieces": ["@activepieces/piece-slack"],
    "piecesFilterType": "ALLOWED"
  }'

Best Practices

Start Restrictive

Begin with allowlist mode and add pieces as needed, rather than blocking later.

Lock Production

Lock project plans in production to prevent unauthorized changes.

Document Allowlists

Maintain documentation of why each piece is allowed/blocked.

Regular Reviews

Audit piece usage quarterly and update allowlists accordingly.

Troubleshooting

Piece Not Appearing

Check:

Platform filter includes the piece
Project plan allows the piece
Piece name is spelled correctly
User has permission to view pieces

Custom Piece Not Loading

Check:

Private registry is accessible
NPM_TOKEN is set correctly
Piece is published to registry
Piece version is compatible

Users See Wrong Pieces

Check:

Project plan is configured correctly
Platform filter is not too restrictive
User is in the correct project
Cache has been cleared

Project Management

Configure project plans

Security Practices

Security considerations

Building Pieces

Create custom pieces

​Overview

Platform Level

Project Level

Private Registry

​Platform Piece Filtering

​Filter Behaviors

​Allow Specific Pieces

​Block Specific Pieces

​Project Piece Plans

​Creating a Project Plan

​Filter Types

​No Filtering (Default)

​Allowlist Mode

​Plan Locking

​Installing Pieces

​Community Pieces

​Private Pieces

​Piece Filtering Logic

​Filtering Rules

​Managing Piece Allowlists

​Adding Pieces to Allowlist

​Common Piece Combinations

​Private Piece Registry

​Registry Setup

​Registry Configuration

​Piece Metadata

​Hidden Pieces

​Checking Piece Availability

​Use Cases

​API Reference

​Best Practices

Start Restrictive

Lock Production

Document Allowlists

Regular Reviews

​Troubleshooting

​Related Topics

Project Management

Security Practices

Building Pieces

Overview

Platform Piece Filtering

Filter Behaviors

Allow Specific Pieces

Block Specific Pieces

Project Piece Plans

Creating a Project Plan

Filter Types

No Filtering (Default)

Allowlist Mode

Plan Locking

Installing Pieces

Community Pieces

Private Pieces

Piece Filtering Logic

Filtering Rules

Managing Piece Allowlists

Adding Pieces to Allowlist

Common Piece Combinations

Private Piece Registry

Registry Setup

Registry Configuration

Piece Metadata

Hidden Pieces

Checking Piece Availability

Use Cases

API Reference

Best Practices

Troubleshooting

Related Topics