#Share Workflows & Apps

You built a workflow or an app spec; another tenant wants to run it. This guide is the authoring-tenant side: declare what your definition exposes, share it, and manage what you've shared. The consumer side — discovering and activating — is in Activate Shared Workflows & Apps; the underlying access model is in Shares & Grants.

All sharing endpoints require a tenant admin. Authenticate with a Personal Access Token (HTTP Basic auth) — enter it once in the Authorize bar above and every Try it below uses it.

#What a consumer gets (and doesn't)

Sharing is read-only and revocable — the consumer activates your definition in their own tenant, where it runs under their configuration and their policies:

• ✅ They can see the definition/spec and activate it.
• ✅ The entity types and JSON schemas you bundle become visible to them when they activate.
• ❌ They can never write to your data.
• ❌ They can never re-share your resources onward.
• ❌ Nothing is copied — revoke the share and access stops on the next request.

#Declare the bundle — the shares block

A workflow or app rarely travels alone: it references entity types and JSON schemas the consumer must be able to see. Declare those once, in the definition itself — a top-level shares block in the workflow definition or app spec document:

Copy{
  "shares": {
    "entityTypes": ["Task", "Project"],
    "jsonSchemas": ["task_priority_v1"],
    "entities": [
      { "entityTypeName": "Project", "scope": "all" },
      {
        "entityTypeName": "Task",
        "scope": "specific",
        "entityIds": ["44444444-4444-4444-4444-444444444444"]
      }
    ]
  }
}

References are names — an entity type's or JSON schema's name, unique within your tenant and portable across environments; each is resolved in your tenant when the manifest is derived, and a name that doesn't resolve rejects the save. A tenant-specific id is accepted in the same positions (entityType in place of entityTypeName).

• entityTypes — catalog + schema visibility ("this type exists, here's its shape"). Each listed type's attribute schema is bundled automatically — no need to repeat it under jsonSchemas. Your rows stay invisible.
• jsonSchemas — extra standalone schemas the definition uses.
• entities — the only way your rows become readable. scope: "all" shares every row of the type; scope: "specific" shares the listed entityIds.

scope: "filter" is reserved and shares nothing. The schema accepts it and the save succeeds, but manifest derivation skips it: a cross-tenant share carries no attribute filter, and granting the type outright would expose every row rather than the filtered subset. Until it is implemented, use scope: "specific" with the ids you mean, or share the whole type knowingly with scope: "all".

The block is grantee-agnostic — it says what travels with the definition, not who receives it. Author it through the normal update endpoints (PUT /definition/workflows/{id}/definition, PUT /definition/specs/{id} — see Workflows and Apps). Editing it later re-syncs every consumer automatically — no re-share, no re-activation.

#Share a workflow

Sharing the definition to a tenant offers them the declared bundle in the same motion; it lands when they activate (their consent):

The consumer activates it in their own tenant, where it runs under their configuration and policy — see Activate Shared Workflows & Apps.

Reference job steps usually need no share of their own. Access follows the binding: a consumer reads the bodies of the jobs you own and bound, because you shared the workflow that pins them. The consumer's activation still checks that every referenced name resolves, so a gap fails there rather than at run time.

The exception is a job you borrowed — one another tenant shared with you and you bound onto your workflow. Your share of the workflow does not pass that job on. Its owner has to share it to the consumer directly; the same stored binding then resolves with nothing else changed. See Job Bindings.

Share a job explicitly when you want a consumer to reference it in their own definitions, rather than only run it through yours:

Sharing a definition discloses what it binds. A consumer that can run your workflow or app can read the bodies of the jobs it pins. Read its default bindings before you share it.

#Share an app spec

Identical motion for apps — the spec's declared bundle is offered alongside, and the consumer's activation accepts it automatically:

The access the app's users need inside the consumer tenant is declared in the spec and applied at activation — see Apps.

#When the block isn't enough

The shares block carries entity types, JSON schemas, and rows — nothing else. Reach for these when you need more:

• Relationship rules, or one-off sharing outside any definition — use the bare per-resource share endpoints (/entity/entity-types/{id}/shares, /entity/entity-types/{id}/data-shares, /entity/relationship-rules/{id}/shares, /schema/schemas/{id}/shares). The primitive is described in Shares & Grants.
• A named bundle of anything you own — author a standalone manifest and publish it per tenant (next).

#Standalone manifests

Every child must name a resource you own (actions is always ["read"]); to share row data, carry both an entity_type child (catalog) and an entity child (rows) for the same type. Publish it to a grantee tenant — an offer; nothing materialises until they subscribe (consumer side):

Edit a bundle later with PATCH /access/manifests/{manifestId} (a new children array replaces the bundle and re-syncs active subscribers). Rescind with PATCH …/publications/{publicationId} { "is_active": false }, or tear down with DELETE.

#Audit & revoke

Everything you've shared, across every resource kind, in one list:

• Per resource: GET /definition/workflows/{id}/shares (same for /definition/jobs/{id}/shares, /definition/specs/{id}/shares, and the entity/schema surfaces).
• Pause a share with PUT …/shares/{shareId} { "is_active": false }; remove it with DELETE. Either way the consumer's access stops on their next request.
• Bundle-derived shares follow their bundle: revoking the definition/spec share (or rescinding a publication) withdraws everything it delivered.

#See also

• Activate Shared Workflows & Apps — the consumer side of this journey.
• Shares & Grants — the access model underneath.
• Workflows · Apps — authoring the definitions themselves.