Private Pieces

What are Private Pieces?

Private pieces are custom integrations that you build and deploy for your own use, without sharing them publicly. They’re perfect for:

Internal APIs

Integrate with your company’s internal services

Custom Tools

Build organization-specific automations

Proprietary Systems

Connect to proprietary or closed-source systems

Confidential Logic

Keep business logic private

Creating Private Pieces

Private pieces are created the same way as community pieces:

Create the Piece

Use the CLI to scaffold your piece:

cd packages/pieces/custom
npm run create-piece

Or manually create in packages/pieces/custom/:

packages/pieces/custom/my-company-api/
├── src/
│   ├── index.ts
│   └── lib/
│       ├── actions/
│       ├── triggers/
│       └── auth.ts
├── package.json
└── tsconfig.json

Implement Your Piece

src/index.ts

import { createPiece, PieceAuth } from '@activepieces/pieces-framework';
import { PieceCategory } from '@activepieces/shared';
import { createTicketAction } from './lib/actions/create-ticket';
import { newTicketTrigger } from './lib/triggers/new-ticket';

export const myCompanyApi = createPiece({
  displayName: 'My Company API',
  description: 'Internal company API integration',
  
  auth: PieceAuth.CustomAuth({
    displayName: 'Connection',
    props: {
      apiKey: PieceAuth.SecretText({
        displayName: 'API Key',
        required: true,
      }),
      environment: Property.StaticDropdown({
        displayName: 'Environment',
        required: true,
        options: {
          options: [
            { label: 'Production', value: 'prod' },
            { label: 'Staging', value: 'staging' },
            { label: 'Development', value: 'dev' },
          ],
        },
      }),
    },
  }),
  
  logoUrl: 'https://your-cdn.com/logo.png',
  categories: [PieceCategory.BUSINESS_INTELLIGENCE],
  authors: ['your-team'],
  minimumSupportedRelease: '0.30.0',
  
  actions: [createTicketAction],
  triggers: [newTicketTrigger],
});

Test Locally

npm run dev

Your private piece will be available alongside community pieces.

Deployment Options

Option 1: Docker (Recommended)

Package and deploy using Docker:

Build Your Piece

npm run build-piece -- --name my-company-api

This creates a distributable package in dist/.

Update Dockerfile

Dockerfile

FROM activepieces/activepieces:latest

# Copy your private piece
COPY packages/pieces/custom/my-company-api/dist /app/packages/pieces/custom/my-company-api

# Install dependencies
WORKDIR /app/packages/pieces/custom/my-company-api
RUN npm install --production

WORKDIR /app

Build & Deploy

# Build custom image
docker build -t my-company/activepieces:latest .

# Push to registry
docker push my-company/activepieces:latest

# Deploy
docker run -d \
  -p 80:80 \
  -e AP_API_KEY="your-api-key" \
  my-company/activepieces:latest

Option 2: Volume Mount

Mount pieces directory for development:

docker-compose.yml

version: '3'
services:
  activepieces:
    image: activepieces/activepieces:latest
    ports:
      - "80:80"
    volumes:
      # Mount private pieces
      - ./packages/pieces/custom:/app/packages/pieces/custom:ro
    environment:
      - AP_API_KEY=${AP_API_KEY}
      - AP_ENCRYPTION_KEY=${AP_ENCRYPTION_KEY}
      - AP_JWT_SECRET=${AP_JWT_SECRET}
      - AP_POSTGRES_DATABASE=${AP_POSTGRES_DATABASE}
      - AP_POSTGRES_HOST=postgres
      - AP_POSTGRES_PASSWORD=${AP_POSTGRES_PASSWORD}
      - AP_POSTGRES_USERNAME=${AP_POSTGRES_USERNAME}
  
  postgres:
    image: postgres:14
    environment:
      - POSTGRES_DB=${AP_POSTGRES_DATABASE}
      - POSTGRES_USER=${AP_POSTGRES_USERNAME}
      - POSTGRES_PASSWORD=${AP_POSTGRES_PASSWORD}
    volumes:
      - postgres-data:/var/lib/postgresql/data

volumes:
  postgres-data:

Start:

docker-compose up -d

Option 3: NPM Registry

Publish to private NPM registry:

Configure Private Registry

npm config set registry https://npm.company.com
npm config set //npm.company.com/:_authToken=${NPM_TOKEN}

Update Package Name

package.json

{
  "name": "@company/piece-my-company-api",
  "version": "0.0.1",
  "private": true
}

Publish

npm run build-piece -- --name my-company-api
cd dist/
npm publish

Install in Activepieces

npm install @company/piece-my-company-api

Environment-Specific Configuration

Manage different configurations per environment:

src/lib/common/config.ts

export function getApiUrl(environment: string): string {
  const urls = {
    prod: 'https://api.company.com',
    staging: 'https://api-staging.company.com',
    dev: 'http://localhost:3000',
  };
  
  return urls[environment] || urls.dev;
}

export function getApiVersion(environment: string): string {
  return environment === 'prod' ? 'v2' : 'v1';
}

Use in actions:

async run(context) {
  const { environment, apiKey } = context.auth;
  const apiUrl = getApiUrl(environment);
  const apiVersion = getApiVersion(environment);
  
  const response = await fetch(
    `${apiUrl}/${apiVersion}/tickets`,
    {
      headers: {
        'Authorization': `Bearer ${apiKey}`,
      },
    }
  );
  
  return response.json();
}

Security Best Practices

Credential Management

Use environment variables for sensitive config:

// Don't hardcode credentials
const apiKey = process.env.COMPANY_API_KEY;  // Bad!

// Use auth system
const apiKey = context.auth.apiKey;  // Good!

Network Security

Use HTTPS for all API calls
Implement IP whitelisting if needed
Use VPN for internal APIs
Validate SSL certificates

const response = await fetch(apiUrl, {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
  },
  // Enforce HTTPS
  agent: new https.Agent({
    rejectUnauthorized: true,
  }),
});

Access Control

Implement role-based access:

async run(context) {
  const { apiKey, userId } = context.auth;
  
  // Verify user has permission
  const hasPermission = await checkPermission(userId, 'create_ticket');
  
  if (!hasPermission) {
    throw new Error('Insufficient permissions');
  }
  
  // Proceed with operation
}

Audit Logging

Log all operations for compliance:

async run(context) {
  const startTime = Date.now();
  
  try {
    const result = await performOperation();
    
    // Log success
    await auditLog({
      action: 'create_ticket',
      user: context.auth.userId,
      status: 'success',
      duration: Date.now() - startTime,
    });
    
    return result;
  } catch (error) {
    // Log failure
    await auditLog({
      action: 'create_ticket',
      user: context.auth.userId,
      status: 'failure',
      error: error.message,
      duration: Date.now() - startTime,
    });
    
    throw error;
  }
}

CI/CD Pipeline

Automate piece deployment:

.github/workflows/deploy-private-pieces.yml

name: Deploy Private Pieces

on:
  push:
    branches:
      - main
    paths:
      - 'packages/pieces/custom/**'

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install dependencies
        run: npm install
      
      - name: Build piece
        run: npm run build-piece -- --name my-company-api
      
      - name: Run tests
        run: npm test
      
      - name: Build Docker image
        run: |
          docker build -t ${{ secrets.DOCKER_REGISTRY }}/activepieces:${{ github.sha }} .
          docker tag ${{ secrets.DOCKER_REGISTRY }}/activepieces:${{ github.sha }} \
                     ${{ secrets.DOCKER_REGISTRY }}/activepieces:latest
      
      - name: Push to registry
        run: |
          echo ${{ secrets.DOCKER_PASSWORD }} | docker login ${{ secrets.DOCKER_REGISTRY }} -u ${{ secrets.DOCKER_USERNAME }} --password-stdin
          docker push ${{ secrets.DOCKER_REGISTRY }}/activepieces:${{ github.sha }}
          docker push ${{ secrets.DOCKER_REGISTRY }}/activepieces:latest
      
      - name: Deploy to production
        run: |
          # Your deployment script
          kubectl set image deployment/activepieces \
            activepieces=${{ secrets.DOCKER_REGISTRY }}/activepieces:${{ github.sha }}

Share pieces across teams:

1. Internal Documentation

Create internal docs:

docs/pieces/my-company-api.md

# My Company API Piece

## Overview
Internal integration with company ticketing system.

## Authentication
1. Go to https://internal.company.com/settings
2. Generate API key
3. Select environment (prod/staging/dev)

## Actions

### Create Ticket
Create a new support ticket.

**Inputs:**
- Title (required): Ticket title
- Description (required): Detailed description
- Priority: Low/Medium/High/Critical
- Assignee: User ID of assignee

**Output:**
- Ticket ID
- Created timestamp
- Ticket URL

## Triggers

### New Ticket
Triggers when a new ticket is created.

**Configuration:**
- Team: Filter by team name
- Priority: Filter by priority level

## Examples

### Example 1: Auto-assign tickets
...

2. Internal Package Registry

Publish to Artifactory/Nexus:

# Configure registry
npm config set registry https://artifactory.company.com/npm/

# Publish
npm publish --registry https://artifactory.company.com/npm/

3. Team Training

Hold training sessions
Create video tutorials
Share example flows
Maintain FAQ

Monitoring and Maintenance

Health Checks

src/lib/actions/health-check.ts

export const healthCheckAction = createAction({
  name: 'health_check',
  displayName: 'Health Check',
  description: 'Check API connectivity',
  requireAuth: true,
  props: {},
  
  async run(context) {
    const startTime = Date.now();
    
    try {
      const response = await fetch(
        `${getApiUrl(context.auth.environment)}/health`,
        {
          headers: {
            'Authorization': `Bearer ${context.auth.apiKey}`,
          },
        }
      );
      
      return {
        status: 'healthy',
        latency: Date.now() - startTime,
        apiVersion: response.headers.get('X-API-Version'),
      };
    } catch (error) {
      return {
        status: 'unhealthy',
        error: error.message,
        latency: Date.now() - startTime,
      };
    }
  },
});

Monitoring Dashboard

Track piece usage:

Execution counts
Error rates
Response times
User adoption

Versioning Private Pieces

Follow semantic versioning:

package.json

{
  "name": "@company/piece-my-company-api",
  "version": "1.2.3",
  "private": true
}

Major (1.x.x): Breaking changes
Minor (x.2.x): New features
Patch (x.x.3): Bug fixes

See Versioning Guide for details.

Troubleshooting

Piece Not Showing Up

Check piece is in correct directory
Verify package.json is valid
Ensure piece is exported properly
Restart Activepieces
Check logs for errors

Authentication Failing

Verify API key is correct
Check environment setting
Confirm API endpoint is accessible
Review network/firewall rules
Check SSL certificate validity

Performance Issues

Add caching for API responses
Implement request debouncing
Optimize data transformations
Review API rate limits
Consider pagination for large datasets

Getting Started

Development

Publishing

What are Private Pieces?

Internal APIs

Custom Tools

Proprietary Systems

Confidential Logic

Creating Private Pieces

Deployment Options

Option 1: Docker (Recommended)

Option 2: Volume Mount

Option 3: NPM Registry

Environment-Specific Configuration

Security Best Practices

CI/CD Pipeline

1. Internal Documentation

2. Internal Package Registry

3. Team Training

Monitoring and Maintenance

Health Checks

Monitoring Dashboard

Versioning Private Pieces

Troubleshooting

Next Steps

Versioning

Testing

Getting Started

Development

Publishing

​What are Private Pieces?

Internal APIs

Custom Tools

Proprietary Systems

Confidential Logic

​Creating Private Pieces

​Deployment Options

​Option 1: Docker (Recommended)

​Option 2: Volume Mount

​Option 3: NPM Registry

​Environment-Specific Configuration

​Security Best Practices

​CI/CD Pipeline

​Sharing Within Organization

​1. Internal Documentation

​2. Internal Package Registry

​3. Team Training

​Monitoring and Maintenance

​Health Checks

​Monitoring Dashboard

​Versioning Private Pieces

​Troubleshooting

​Next Steps

Versioning

Testing

What are Private Pieces?

Creating Private Pieces

Deployment Options

Option 1: Docker (Recommended)

Option 2: Volume Mount

Option 3: NPM Registry

Environment-Specific Configuration

Security Best Practices

CI/CD Pipeline

Sharing Within Organization

1. Internal Documentation

2. Internal Package Registry

3. Team Training

Monitoring and Maintenance

Health Checks

Monitoring Dashboard

Versioning Private Pieces

Troubleshooting

Next Steps