Permission Expressions

In an embedded deployment, not every customer should see every integration or automation workflow. A free-tier user shouldn't see the Salesforce integration you sell as a premium add-on; an EU customer shouldn't see an integration that isn't GDPR-cleared; a beta feature should reach only the accounts you've flagged. Permission expressions let you encode those rules directly on an integration, an automation workflow project, or one of their workflows, evaluated per connected user at request time.

How it works

Each integration, each automation workflow project, and each of their workflows carries an optional permission expression: a SpEL expression that must evaluate to true for the requesting connected user to see that resource.

When your product lists the integrations or automation workflow projects available to a connected user, the platform evaluates each expression against that user's identity and metadata and filters out anything that doesn't pass.

Connected user requests their integrations / automation workflow projects
        │
        ▼
For each integration / project / workflow:
  permission expression blank? ──► visible
  expression evaluates to true? ──► visible
  anything else (false or error) ──► hidden

Fail-closed semantics

The evaluator fails closed, which is the safe default for an access decision:

• A blank or absent expression means no restriction — the integration is visible to everyone. (Most integrations have no expression.)
• An expression that evaluates to true makes the integration visible.
• Anything else hides it — false, a malformed expression, a null dereference, any evaluation error. A typo in an expression hides the integration rather than exposing it.

What the expression can reference

The expression is evaluated against a context built from the requesting connected user:

metadata is the workhorse. Your backend writes it with PATCH /api/embedded/v1/me (end-user JWT) or PATCH /api/embedded/v1/{externalUserId} (API Key), sending a flat JSON object; name and email are lifted onto the connected user and everything else is stored as metadata. That lets you drive integration visibility off your own entitlement model without ByteChef needing to know what a "plan" or a "region" is.

Examples

Show an integration only to paid plans:

metadata['plan'] == 'pro' || metadata['plan'] == 'enterprise'

Restrict a workflow to a specific region:

metadata['region'] == 'eu'

Gate a beta integration to explicitly flagged accounts (note the quotes — metadata values are strings):

metadata['betaIntegrations'] == 'true'

Limit a sensitive integration to internal users by email domain:

email != null && email.endsWith('@yourcompany.com')

Setting an expression in the UI

Each expression is a multi-line Permission Expression text field, scoped to the resource it gates. Leaving it empty means no restriction.

Integrations:

• In Embedded → Integrations, the integration create/edit dialog (New Integration / edit) has a Permission Expression field alongside the component, name, description, category, and tags — it gates the whole integration.
• In the integration's workflow list, each workflow row exposes its own Permission Expression field so you can gate individual workflows inside an otherwise broadly visible integration.

Automation workflow projects:

• The Automation Workflow Project dialog (in Embedded → Automations) has a project-level Permission Expression field.
• Each workflow's Automation Workflow dialog has its own Permission Expression field.

Setting an expression through the admin API

The same expressions are settable programmatically, scoped to the resource they gate.

Integrations:

• The integration-level expression is set as part of the integration update (a permissionExpression field on the integration), so it is saved together with the rest of the integration in a single write.
• updateIntegrationWorkflowPermissionExpression — sets the expression on a single workflow within an integration.

Automation workflow projects:

• The project-level expression is folded into createAutomationWorkflowProject / updateAutomationWorkflowProject as a permissionExpression argument, so it is saved with the rest of the project in a single write. A null argument leaves any stored expression unchanged; an empty string clears it.
• A workflow's expression can be passed on createAutomationWorkflowProjectWorkflow, and changed later with updateAutomationWorkflowProjectWorkflowPermissionExpression.

A workflow-level expression lets you ship an integration or automation workflow project broadly while still gating individual workflows inside it — e.g., the project is visible to everyone, but its "bulk export" workflow only to enterprise accounts. The project-level expression behaves like the integration-level one: when it evaluates false, the whole project (and all its workflows) drops out of that connected user's catalog.

Where it fits

Permission expressions are an advisory visibility filter, not a hard security boundary on execution. They decide what a connected user is offered; tenant-isolated security is what guarantees one tenant can't reach another's data or credentials. Use expressions to shape each customer's catalog; rely on tenant isolation for the actual blast-radius guarantee.