#Accept & Activate

Another tenant wants you to use their workflow, app spec or data. They put it in a manifest and offer it to your tenant. This guide is your side: review the offer, accept it, check what you received, then activate it. Activation is your tenant's use of a shared definition: your configuration, your triggers and integrations, your policies, running entirely in your tenant.

The owner's resources stay read-only for you. Nothing of theirs is copied into your tenant, and they can withdraw at any time. The owner's side is in Share with Another Tenant. What a share lets you do is in Shares & Grants.

Authenticate with a Personal Access Token (HTTP Basic auth). Enter it once in the Authorize bar above and every Try it below uses it.

#1. Find what's offered to you

Pass direction=incoming. Each manifest has the owner's tenant_id, its name, description, members, and publication: your offer, with its status (offered or accepted). Offers you declined, and offers the owner withdrew, are not listed.

Until you accept, a member's resource_name is null. The names of the owner's resources are not visible to you yet. To see exactly what you'd receive, with names, read the resolved view:

Each element is one resource (resource_type, resource_id, resource_name, resource_version, permitted_actions) with a provenance that says why it's included. See Preview the effect.

#2. Accept or decline

Nothing is shared until you accept. Before that, a shared workflow can't be activated (404), a shared app can't be activated (403, "App spec is not visible to this tenant."), and the owner's resources read as not found.

The response has manifest_id, publication_id, status and accepted_at. Every resource in the offer is shared with your tenant as soon as the call returns.

• The answer always applies to your own offer. Nobody else can accept for your tenant, and that includes the owner.
• Sending the same answer again returns it unchanged.
• Decline with { "status": "declined" }. This removes everything the offer shared. A declined offer is dropped from your incoming list, and the manifest reads as 404 for you. You can still change your mind and accept later.
• Read your standing answer at any time, including after you declined or the owner withdrew:

When the owner offers a withdrawn or declined manifest again, it comes back as offered and you must accept it again. Your activations are kept and work again once you have accepted.

With no offer addressed to your tenant, both acceptance calls answer 404 (details.code PUBLICATION_NOT_OFFERED).

#3. Check what you received

Pass direction=inbound. Each row is one resource shared with your tenant: resource_type, resource_id, the owner as grantor_tenant_id, permitted_actions, and sources[]. Each source names the manifest (manifest_id, manifest_name) and publication behind the share, and its provenance. A resource offered by two manifests you accepted appears once, with two sources.

Find each resource with the usual endpoints:

• Workflows appear in GET /definition/workflows with "source_type": "shared".
• App specs are not listed by GET /definition/specs. Fetch one by id with GET /definition/specs/{id}, using the resource_id from the share.
• Entity types, JSON schemas and job versions read by id, like your own. A shared entity type's attribute schema is readable too. A shared job appears in GET /definition/jobs with "source_type": "shared", and only the version the owner listed is readable.

#4. Prepare

A shared definition may need three things from your tenant before it runs:

1. Secrets. A definition never holds a credential: it reads a config key, and you wire that key to a secret stored in your tenant, for example "API_KEY": "{{ secrets.tenant.PARTNER_API_KEY }}" in a workflow's env (see Secrets). Store each value first:

2. Configuration. A workflow may need env values from you, and an app may need config values. When a definition names a config schema, your values are validated against it. See Config Schemas. If a value is missing or invalid, activation fails, and the error details say which values are wrong. So you can safely attempt activation and read the response.
3. An external company (apps only). Each app integration belongs to one. See Provisioning.

#5. Activate a workflow

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

For a workflow you don't own, this answers 404 ("Workflow not found.") unless you have accepted a manifest that shares it. The response is your operating state:

• The workflow, with source_type: "shared" and the owner's owner_tenant_id.
• Triggers, with their webhook URLs and cron schedules, live immediately.
• Webhook signing secrets, for webhook triggers whose definition declares verification. These are returned once, in the response that created them. Store them straight away. Afterwards you can only rotate them.
• 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.

Manage it afterwards:

• GET /workflows/{id}/config returns your env, your own job_bindings, and job_bindings_detail: what each referenced job resolves to, and at which level.
• Every config write merges. A key you send is set, a key sent as null is unset, and a key you don't mention keeps its value. So a write carrying only job_bindings never disturbs your env. If another admin changed the config between your read and your write, the server re-applies your change over theirs. If it can't, you get a 409: read the config again and retry.
• Point a referenced job at a different job with PATCH /workflows/{id}/config/job-bindings, by job id. See Job Bindings. Activation and config writes refuse a state that couldn't run, so a bad binding fails here rather than at 3am.
• Pause or resume a trigger with PUT /workflows/{id}/triggers/{triggerId}/disable or …/enable.
• Rotate a webhook secret with POST /workflows/{id}/triggers/{triggerId}/secret, or re-activate with "regenerate_secrets": "all". Revoke it with DELETE.

#6. Activate an app

There is no separate activate call for apps. Creating your app config is the activation, and name is required the first time:

For a spec you don't own, this answers 403 ("App spec is not visible to this tenant.") unless you have accepted a manifest that shares it.

The spec's own access policy is applied for you (policy_source: "spec"). Pass policy_id, or an inline policy, to use your own instead. Applying the policy is reported as policy_sync_status on your app config. Read it back with GET /apps/{specId}/config and check for "synced".

Then set up how the app is used:

• Integrations: one per external company that uses the app.

• Bearer tokens, for providers that authenticate with a token: PUT /apps/{specId}/integrations/{integrationId}/token with a name. The raw token is returned once. While one is active, another call answers 409. Add ?rotate=true to revoke it and issue a new one.
• Job bindings: an app's job steps name keys. Bind a key to a different job for your tenant with PATCH /apps/{specId}/config/job-bindings (a job id or name@version), or for one integration with PATCH /apps/{specId}/integrations/{integrationId}/job-bindings (a job id). Unlike a workflow, an app is not checked at activation: an unbound key surfaces when the step runs. See Job Bindings.
• Principal overlays: per-company, per-team or per-user config, merged over the spec's own values for that scope.

For the company tier, your own tenant is the company, so 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, and assign one with PUT /apps/{specId}/users/{authUserId}/policy.

Full app-surface detail: Apps.

#The owner's data in your tenant

• Your own rows of a shared entity type need nothing more. Store and query them like any of your data.
• The owner's rows are shared only when the manifest lists them (an entity member). Even then, a share makes them visible to your tenant, not to every user in it. A principal reads them through a read grant from you on the shared type or row. When the owner shares all rows of a type, a user whose role reads all entities (such as tenant_admin or viewer) reads them too, without a grant. A token bound to a policy always needs the grant. See Shares & Grants.

#When the owner changes or withdraws

• If the owner changes the manifest, you get the change straight away. New resources are shared, and removed ones stop being readable. You don't need to accept again.
• If the owner withdraws the offer or deletes the manifest, everything it shared stops. A shared workflow answers 404 when you try to activate it, and your configuration of it becomes unreadable. Your stored configuration is kept, and works again if the owner offers the manifest again and you accept.
• A job the definition binds, but that the owner borrowed from a third tenant, reaches you only through a manifest from that job's owner. See Job Bindings.

#Tear down

• App: DELETE /apps/{specId}/config removes your activation, along with its integrations, tokens and principal overlays.
• Workflow: disable its triggers to stop intake (PUT /workflows/{id}/triggers/{triggerId}/disable). Your config stays for a later re-enable.
• Decline offers you don't need (PUT /access/manifests/{manifestId}/acceptance with "declined"), and remove any grants you added for shared resources.

#See also

• Share with Another Tenant: the owner's side.
• Shares & Grants: the access model.
• Config Schemas · Job Bindings
• Workflows · Apps · Secrets · Provisioning