#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": ["11111111-1111-1111-1111-111111111111"],
    "jsonSchemas": ["22222222-2222-2222-2222-222222222222"],
    "entities": [
      {
        "entityType": "11111111-1111-1111-1111-111111111111",
        "scope": "all"
      },
      {
        "entityType": "33333333-3333-3333-3333-333333333333",
        "scope": "specific",
        "entityIds": ["44444444-4444-4444-4444-444444444444"]
      }
    ]
  }
}

• 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 not yet supported.)

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.

If the workflow uses reference job steps, share those job definitions with the same tenant too — the consumer's activation validates that every referenced job is resolvable:

#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.