Docs / Activate Shared Workflows & Apps
Authorize

#Activate Shared Workflows & Apps

Another tenant shared a workflow or app spec with you. Activation is your tenant's use of it: your configuration, your triggers and integrations, your policies — running entirely in your tenant. The author's artifacts stay read-only; they can revoke at any time, and nothing of theirs is copied into your tenant. The authoring side is in Share Workflows & Apps; the underlying access model is in Shares & Grants.

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

#Discover what's shared with you

One list covers every resource kind shared to your tenant — workflows, app specs, referenced job definitions, entity types, JSON schemas:

GET/access/sharesList what's been shared with you (direction=inbound)API docs ↗Try it

Pass ?direction=inbound. Each row carries a resource_type + resource_id; fetch the details per id:

  • Workflows also appear directly in GET /definition/workflows, marked "source_type": "shared".
  • App specs don't appear in the spec list — fetch them by id with GET /definition/specs/{id}.
  • Standalone manifest offers appear under GET /access/manifests?direction=incoming (accepting them).

#Prepare

Three things a shared definition may need from your tenant before it runs:

  1. Secrets. Definitions reference secrets by name ({{ secrets.… }} — see Secrets); the values come from your tenant. Create each one the author's definition expects:
POST/access/secretsCreate a secret the definition referencesAPI docs ↗Try it
  1. Environment variables. A workflow definition may require env values from the activating tenant. Activation fails while any are unset — the error's details name the missing ones under missing_env_vars, so it's safe to attempt activation and read the response.
  2. An external company (apps only) — each app integration is scoped to one; see Provisioning.

#Activate a workflow

One call creates your tenant's configuration and brings the workflow live:

POST/workflows/{id}/activateActivate a shared workflow in your tenantAPI docs ↗Try it

The response is your operating state:

  • Triggers, with their webhook URLs and cron schedules, now live.
  • Webhook signing secrets — returned once, on the response that minted them. Store them now; afterwards you can only rotate.
  • The applied policy. By default the workflow runs under the policy its definition declares (or your role-based access when it declares none); pass policy_id (or an inline policy) to run it under your own instead.
  • If the author bundled entity types or JSON schemas, activating is your consent — they land in your tenant (below).

Manage it afterwards:

PUT/workflows/{id}/configUpdate your tenant's env overlayAPI docs ↗Try it
GET/workflows/{id}/triggersList your live triggersAPI docs ↗Try it
  • Read the effective config back with GET /workflows/{id}/config.
  • Pause/resume a trigger: PUT /workflows/{id}/triggers/{triggerId}/disable / …/enable.
  • Rotate a webhook secret: POST /workflows/{id}/triggers/{triggerId}/secret (or re-activate with "regenerate_secrets": "all"); revoke with DELETE.

#Activate an app

There is no separate activate verb for apps — creating your app config is the activation (name is required the first time):

PUT/apps/{specId}/configActivate a shared app (create your app config)API docs ↗Try it

The spec's declared access policy is applied for you; pass policy_id (or an inline policy) to substitute your own. Then wire up how it's consumed:

  • Integrations — one per external company that uses the app:
POST/apps/{specId}/integrationsAdd an integration for an external companyAPI docs ↗Try it
  • Bearer tokens (providers that authenticate with a token): PUT /apps/{specId}/integrations/{integrationId}/token — the raw token is returned once; ?rotate=true reissues.
  • Principal overlays — per-company / per-team / per-user config merged over the spec's defaults (defaults → company → team → user):
PUT/apps/{specId}/principals/{type}/{principalId}Set a principal's config overlayAPI docs ↗Try it

For the company tier, your own tenant is the company — pass the self sentinel as {principalId} (an integration's external_company_id is not a principal id). self also works for user (you); team needs an explicit team id.

  • App roles — list the spec's roles with GET /apps/{specId}/policies; assign one with PUT /apps/{specId}/users/{authUserId}/policy.

Full app-surface detail: Apps.

#Borrowed entity types & JSON schemas

Activating is the consent step that accepts the author's declared bundle. The entity types and JSON schemas (and any rows they chose to share) become visible in your tenant — this may take a moment; verify under GET /access/shares?direction=inbound.

  • Your own rows of a borrowed type — the share is all you need: store and query them like any of your data.
  • The author's rows (when they shared data) — visibility isn't permission: your principal additionally needs your own read grant on the resource. See Shares & Grants.
  • The author can evolve the bundle later; your tenant re-syncs automatically.

#Accept a standalone manifest offer

Offers published to you appear under GET /access/manifests?direction=incoming. Accepting is a subscription — the bundle's shares materialise in your tenant; unsubscribe and they disappear:

POST/access/manifests/{manifestId}/subscriptionsSubscribe (accept the offer)API docs ↗Try it

Withdraw with DELETE /access/manifests/{manifestId}/subscriptions.

#Tear down

  • App: DELETE /apps/{specId}/config removes your activation — integrations, tokens, and principal overlays go with it.
  • Workflow: disable its triggers to stop intake (PUT /workflows/{id}/triggers/{triggerId}/disable); your config stays for a later re-enable.
  • Unsubscribe from manifests you no longer need, and remove any grants you added for borrowed resources.

#See also