Activepieces Access & Isolation

This page is the reference for how AgentLane connects to Activepieces, what “an isolated instance for a partner” actually means in each tenancy mode, which endpoints drive provisioning and who may call them, and the exact pipeline each setup runs.

For the operational walkthrough, see Admin: Provision a Partner. For why Activepieces is the engine at all, see Workflow Engine.

Who can reach Activepieces

AgentLane itself reaches Activepieces only from inside the container network. Whether anyone else can is a deployment choice, and it defaults to no.

• AgentLane always talks to Activepieces internally. ACTIVEPIECES_BASE_URL is a server-to-server address the API container resolves on the Docker network — http://activepieces-app:80 in production, http://localhost:8090 in development. Every admin call and every webhook trigger goes over that address. It is never a public URL.
• The editor UI can optionally be published, and is not by default. Setting ACTIVEPIECES_DOMAIN records a hostname; the public Traefik router is written only when ACTIVEPIECES_PUBLIC_UI=true as well (deploy/scripts/deploy.sh). This is deliberately two switches rather than one: every deployment that runs Activepieces at all sets ACTIVEPIECES_ENABLED=true, and that alone used to publish the editor.

• Partners and clients never get Activepieces UI access. The Portal does not proxy the Activepieces editor. Instead, GET /partners/:id/automation/workflows/:workflowId/viewer returns a native, read-only view: the workflow’s template definition plus recent run history.
• Every trigger originates from AgentLane. AutomationWebhookResolver composes the absolute webhook URL against the internal base URL at trigger time, so inbound business events hit the AgentLane API first and are dispatched inward from there.

What isolation a partner actually gets

AUTOMATION_TENANCY_MODE selects between two models. Neither gives a partner their own Activepieces deployment — resolve_endpoint returns the same global ACTIVEPIECES_BASE_URL for every partner in both modes.

In shared mode ensureTenant does not create anything — it returns the single configured ACTIVEPIECES_PROJECT_ID, the platform admin’s own default project. Activepieces CE has no “current user’s default project” concept, and every project-scoped endpoint requires an explicit project ID, so this value must be set or provisioning fails immediately with a clear error.

project mode is technically supported and exercised by ensureTenant (list by display name, create if absent), but shared remains the default. Before switching, run a capability matrix against the exact candidate image — a project ID alone does not establish tenant isolation.

How AgentLane authenticates

Not with a static API key. There isn’t one to use.

Activepieces CE has no durable server-to-server API key: POST /v1/api-keys is gated behind platform.plan.apiKeysEnabled, which defaults to false and requires a paid Enterprise license. Confirmed live against the pinned activepieces/activepieces:0.82.0 image — the route 404s even for the platform-admin user on an unlicensed instance.

The only Bearer token that authenticates /v1/projects, /v1/flows and /v1/app-connections on CE is a user login JWT. So ActivepiecesSessionAuthService:

1. Signs in via POST /v1/authentication/sign-in using ACTIVEPIECES_ADMIN_EMAIL / ACTIVEPIECES_ADMIN_PASSWORD — a real Activepieces user created through that instance’s own first-run signup, which grants platform-admin rights to the first user automatically.
2. Caches the resulting JWT (roughly a 7-day lifetime on the pinned build).
3. Refreshes it proactively 10 minutes ahead of expiry, and reactively whenever the HTTP client sees a 401 and calls invalidate().

No static key is ever stored on the instance row: apiKeyEncrypted is written as null during provisioning. These admin credentials are full platform-admin access to every partner’s automation resources — keep them only in trusted infrastructure config, never in partner-visible settings.

Endpoint surface

All provisioning routes live under partners/:id/automation and are ADMIN-only, guarded by RolesGuard. The one exception is the viewer, which also accepts the owning PARTNER.

provision, reprovision and the deprovision route each write an audit log entry (automation_instance.provision_requested and siblings) recording the acting user.

What a partner is allowed to see

GET /partners/me/automation is deliberately redacted. A PARTNER caller never receives baseUrl, projectId, or lastError — those are infrastructure detail and, in shared mode, would describe resources shared with other partners. Instead the twelve internal steps collapse into four coarse stages:

The response carries errorPublic — a client-safe message — never the internal error. That split is what lets a partner see a real “provisioning failed, here’s what to do” state without leaking infrastructure shape.

The setup pipeline

Provisioning runs synchronously within the request and is recorded step by step by AutomationProvisionStepRecorder. Each step is individually timed and records success, failure, warnings, and both an internal and a client-safe error.

If any step throws, the instance is marked failed with the recorded error. Missing credentials produce a targeted message naming the offending steps: Could not activate: missing credential for step(s) ….

Repair, recreate and teardown

POST .../reprovision takes a mode:

Instance states

unprovisioned ──Provision──► provisioning ──► ready
                                  │
                                  └──failure──► failed ──Provision (retry)──► provisioning

ready ──Reprovision (repair)───► provisioning   (rebuilds in place, no teardown)
ready ──Reprovision (recreate)─► provisioning   (full teardown, then full provision)
ready ──Deprovision────────────► unprovisioned  (permanent)

There is no separate “retry” action — provisioning a failed instance re-runs the same pipeline.

A run that crashes mid-flight would otherwise leave the row stuck in provisioning or deprovisioning forever, so AutomationProvisionTimeoutJob reaps anything older than AUTOMATION_PROVISION_TIMEOUT_MINUTES (default 15).

Configuration

Rolling back to a non-Activepieces posture is ACTIVEPIECES_ENABLED=false, which trips feature_gate on every subsequent attempt.