--- title: Secure Connections sidebar_position: 10 --- # Secure Connections :::note Availability Secure Connections require a **Sending Connection** configured by an administrator for your deployment. Contact your admin if you do not see the controls described below. ::: Secure Connections let you share an individual resource (a model or an artifact) with a partner organization through a **Sending Connection** that an administrator has already configured. Once a resource is shared through a connection, the Istari Digital Platform keeps the partner's copy in sync as you upload new revisions and produce new artifacts from it. Each share carries an **access level** (either **View access** or **Edit access**) that controls what the partner can do with their copy. View access is read-only; Edit access lets the receiving organization run jobs on the resource and add their own revisions to their copy. The access levels you can pick are bounded by the connection's ceiling, which the sending administrator sets (see [Per-File Access Level](#per-file-access-level-view-vs-edit)). > Secure Connections apply to **models and artifacts** only. Systems cannot be shared through a Secure Connection as a whole. > **File size limit:** Secure Connections cannot transfer individual files larger than ~2 GB. Files above this cap are rejected on the sending side and never reach the partner organization. Support for larger files is planned for a future version. > **Unsharing signals revocation.** The receiving platform attempts to honor revocation by _tombstoning_ its copy of the resource. See [Revocation and Tombstoned Files](#revocation-and-tombstoned-files) below for what this does and what it cannot do. > **Something not working?** If a file is not appearing on the partner side or has stopped syncing, ask your administrator to consult [Debugging Secure Connections](../admin-guide/secure-connections-debugging.md). --- ## See Which Partners a Resource Is Shared With Open the Resource's details pane on the **Resources** page (or from a system branch or commit). The **Connections** row lists the partner organizations currently receiving this resource. If the resource is not shared with any partner, the row shows **None**. --- ## Share a Resource with a Partner Organization 1. Open the resource and click the **Share** button (share icon) in the resource's action bar. 2. The **Share \** dialog opens in user-sharing mode by default. Click **Share with external connection** (globe icon, top-right of the dialog) to switch to Secure Connections sharing. 3. In the **Add organization** field, search for and click the partner organization you want to add. Only sending connections that you have not already added are shown. 4. The selected connections appear under **Connections with access (N)**. To remove one, click the remove button next to its name. 5. For each connection that permits editing, set the **access level** (View or Edit) — see [Per-File Access Level](#per-file-access-level-view-vs-edit) below. 6. Review the certification box and check the required boxes (see [Confirmation Prompts](#confirmation-prompts) below). 7. Click **Share** to save. A toast confirms **External connection sharing updated.** The dialog states: **Sharing with Secure Connections does not cascade; child resources must be manually shared.** To switch back to sharing with internal users, click **Share with users** (people icon, bottom-left). > **Required role:** Editor or above on the resource. --- ## Share from Python Everything the **Share** dialog does is also available in the Python SDK, so sharing can be part of an automated pipeline. `V3Client` in `istari-digital-client` provides: - `list_shareable_sending_connections()` — the connections you may share to, with each connection's access ceiling - `share_file_to_sending_remote()` — share a resource at View or Edit access - `list_sending_remote_shares_for_resource()` — the partners a resource is currently shared to - `revoke_file_from_sending_remote()` — stop sharing The same rules apply as in the web app: models and artifacts only, Editor access on the resource, and the connection's limits are enforced. Sync is asynchronous, so the partner receives the file on the next sync cycle rather than when the call returns. See [Python Client 203 — Share with a partner](../../tutorials/automate/203-share-with-partner.md) for a worked example and the [V3Client reference](../../icbs-build-python/v3/v3-client.mdx#secure-connection-sharing) for signatures. --- ## Confirmation Prompts Because Secure Connections send data to an external organization, every change that adds or removes a partner — or that pushes new content to one — must be explicitly confirmed before it can be saved. The confirmation always appears as an **amber-bordered certification box** inside the dialog, with a checkbox you must tick before the action button enables. ### When Adding a Partner The box lists each partner that will gain access: > This resource will be shared with: > > - _Partner Org A_ > - _Partner Org B_ > > **Confirm External Organization(s) will gain access to this model.** The subject ("this model", "this artifact", "this revision", or "any artifacts produced by this tool run") changes depending on the action. ### When Removing a Partner The box presents a checkbox describing what the partner retains: > **Confirm External Organization(s) will retain their copy of this model and will stop receiving new updates.** Removing a partner from a resource's access list stops future synchronization **and sends a revocation signal** across the connection. On the next sync cycle, the partner's receiving platform attempts to honor it by **tombstoning** its copy — best-effort and eventually consistent, so it is not instantaneous. Revocation **cannot** purge data the partner has already exported, downloaded, or forwarded outside the platform. See [Revocation and Tombstoned Files](#revocation-and-tombstoned-files) below. If your change adds **and** removes partners in a single save, both checkboxes are shown and both must be checked. --- ## Per-File Access Level (View vs. Edit) When you add a connection in the share dialog, that share gets an **access level** that determines what the partner can do with their copy: - **View access** (eye icon) — the partner's copy is read-only. They can view it but cannot run jobs against it or add revisions. - **Edit access** (pencil icon) — the partner can run jobs on their copy and add their own revisions to it. Their edits stay on their copy; they are not sent back to you. The selector that appears for each connection depends on the connection's **Permitted Access**, which your administrator sets on the connection: - If the connection permits editing, a **View access / Edit access** dropdown appears for that row, defaulting to **View access**. - If the connection only permits viewing, the row shows a locked **View access** badge (with the tooltip _"This connection only permits view access."_) and no selector. When you grant **Edit access**, the certification box heading reads **"These External Organization(s) will gain edit access:"** and you must confirm that those organizations will be able to run jobs and edit their copy of this resource. Changing a share's level re-requires confirmation. Re-opening the share dialog shows each connection under **Connections with access** at its saved access level. If an administrator later turns the connection's **Allow Edit Access** off, every share on that connection at Edit access is downgraded to View access automatically; the administrator confirms how many shares are affected before the change is saved. The partner keeps its copy but can no longer run jobs on it or add revisions. --- ## Actions That Automatically Push Data to Partners Once a resource is shared through a Sending Connection, these actions automatically propagate the result to every partner the resource is shared with. Each one shows the same certification box before it can complete: | Action | Certification subject | Where it appears | | ------------------------------------------------ | ----------------------------------------- | ------------------------------------------------------------ | | Upload a new revision of the resource | _this revision_ | **Upload Version** dialog | | Run a function that produces artifacts | _any artifacts produced by this tool run_ | **Function** panel on the resource page | | Extract artifacts from a system branch or commit | _any artifacts produced by this tool run_ | **Extract \?** dialog from a system Resource tree | In every case, the action button (**Upload**, **Execute Function**, **Extract**) stays disabled until the certification checkbox is ticked. If the resource is not shared with any partner, the certification box is not shown and the action proceeds normally. --- ## Finding Artifacts Shared to You Individually On the receiving end, an artifact that is shared on its own — without its parent model — does not appear in the default **Resources** view, which lists models grouped with their child artifacts. You can still find them via the global **Search** by file name. --- ## Working with Resources Received from a Partner When a partner shares a resource with you, what you can do with your copy depends on the access level they granted: - **View access** — the resource is read-only. **Create Job**, **Extract**, and **Add Version** are disabled, with a tooltip explaining the resource is view-only. - **Edit access** — you can run jobs on your copy and add your own revisions. The revision list shows a plus (**+**) button to add a revision, and any artifacts or jobs you create stay local to your instance. ### Local vs. Remote Revisions On an editable received resource, each revision in the versions list carries a **source icon** so you can tell where it came from: - A **router icon** marks a **remote revision** synced from the partner (tooltip _"Source: \"_). - A **home icon** marks a **local revision** you added on your own instance (tooltip _"Revision local to this Istari Digital instance"_). As the partner uploads new revisions on their side, they continue to sync in and appear with the router icon alongside your local revisions. ### Sharing a Received Resource Onward A resource you received from a partner can be shared over one of your own organization's Sending Connections only if the partner enabled **onward sharing** on the connection it arrived through. When they did, the Share dialog lists your sending connections as usual; when they did not, the resource cannot be added to any connection and the dialog says so. An onward share is capped at the access level you received the resource at: a resource received at View can only be shared onward at View. It also depends on the original share staying in place — see [case 3](#3-the-original-share-is-withdrawn) below. ### Lineage Open the **Lineage** tab in the resource details panel to see provenance. A remote-sourced revision connects to a synthetic **Receiving Remote** source node (dashed border, router icon) through an edge labeled **"synced from"**, and the revision you are viewing is marked as the **anchor**. Jobs you run on your copy and the artifacts they produce appear in the same graph as the usual resource → job → artifact chain. --- ## Cases Where a Resource Is Automatically Unshared Sending Connections can enforce up to two limits, both optional, that an administrator sets when configuring the connection (a third case, specific to resources you received from a partner, is covered [below](#3-the-original-share-is-withdrawn)): - A **Permitted Infosec Level**, the maximum classification the connection allows. - A set of **Tag Rules**, checks over the Resource's control tags that yield an **Allow** or **Block** verdict for each Resource. Every check that matches a Resource applies, and one matching Block check blocks the Resource regardless of the other matches. Those tags are the same need-to-know controls assigned to the Resource and to users. See [Control Tag](../../intro/key-concepts/sharing-security-access-control.md#control-tag). Whenever the platform detects that a resource no longer fits within these limits, the resource is removed from that connection automatically. This can happen either by changing the resource or by changing the connection. ### 1. The Resource Outgrows the Connection A resource is **removed from a connection** when one of these changes makes the resource ineligible: - The resource's **infosec level is raised** above the connection's Permitted Infosec Level. - A **control tag change** causes the connection's tag rules to reach a **Block** verdict for the resource. When this happens: - The partner organization **keeps the copy of the resource (and any earlier revisions) it has already received**, but stops receiving any further updates from this connection. - Other Sending Connections whose limits still cover the resource's new classification continue to sync as normal. - The **Connections** row on the resource's details pane updates to reflect the new set of partners. ### 2. The Connection Is Tightened Past Its Shared Resources An administrator can also tighten a Sending Connection so that a resource already shared through it no longer qualifies: - **Lowering the Permitted Infosec Level** below the level of a currently shared resource. - **Saving a tag ruleset** that reaches a **Block** verdict for a currently shared resource. Before the change is saved, the administrator sees how many shared resources it affects and must acknowledge that the partner organization will lose access to them. Once confirmed, every affected resource is **unshared from the connection automatically** — you are not asked to unshare it first. When this happens: - The resource stops receiving any further updates from this connection. - A **revocation request** is sent to the receiving instance so it can lock the transferred files. The partner's copy (and any earlier revisions) may remain readable until the receiving platform honors the revocation by **tombstoning** it — after which each revision's content is deleted and its metadata cleared. See [Revocation and Tombstoned Files](#revocation-and-tombstoned-files) for what this does and what it cannot do. - Other Sending Connections whose limits still cover the resource continue to sync as normal. - The **Connections** row on the resource's details pane updates to reflect the new set of partners. If a resource you own disappears from a connection, check with your administrator whether the connection's limits changed. ### 3. The Original Share Is Withdrawn If you shared a **received** resource onward (see [Sharing a Received Resource Onward](#sharing-a-received-resource-onward)), that onward share is revoked automatically when the partner revokes the original resource, archives the connection it came through, or turns onward sharing off on that connection. If the partner lowers your access to View, an onward share made at Edit is revoked as well; onward shares made at View stay in place. The organization you shared onward with receives a revocation request exactly as if you had unshared the resource yourself. --- ## Revocation and Tombstoned Files When you **unshare** a resource from a Sending Connection, the platform: - Stops sending further updates for that resource - Sends a **revocation** signal across the connection. On the next sync cycle, the partner's receiving platform attempts to honor it by **tombstoning** its copy. ### What a Tombstoned File Is A **tombstoned** file is a received resource whose content has been **revoked**. When the receiving platform processes a revocation, it: - **Deletes each revision's content**, so the bytes can no longer be downloaded. - **Clears the file's metadata**, leaving an empty placeholder. Revocation is applied **per revision**, so every revision of the file is zeroed, including any revision added locally on the receiving side. > **Tombstoning is best-effort and eventually consistent.** Revocation crosses an organizational boundary through the transfer mechanism, so it is not instantaneous: > > - The sending side re-emits the revocation each sync cycle, and the receiving side retries until the tombstone succeeds. > - Until then, the receiving copy may still be readable. > - Revocation of a resource the partner never received is a no-op. ### See Also - [Secure Connections (Admin Guide)](../admin-guide/secure-connections.md#revocation-and-tombstoning) for administrator-facing detail.