> ## Documentation Index
> Fetch the complete documentation index at: https://docs.manus.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Enumerate and govern shareable team assets for DSPM workflows

<sup>Questions or issues? Contact us at [api-support@manus.ai](mailto:api-support@manus.ai).</sup>

# Shared Team Asset Governance

Lets enterprise tenant administrators enumerate the team's sharable surface (sessions, files, web-publish targets, projects) and override individual share scopes from a Data Security Posture Management (DSPM) workflow. The API is split across two services so the read and write halves can be authenticated with separate, independently-rotated keys.

## Endpoints

<CardGroup cols={2}>
  <Card title="List shareable assets" icon="list" href="/enterprise/v2/team.asset.list">
    Enumerate every share the team has issued for one asset type, with filters for owner, time range, keyword, and raw permission
  </Card>

  <Card title="Update a share scope" icon="lock" href="/enterprise/v2/team.asset.update_scope">
    Admin-override a share's permission and write a `note` into the audit trail
  </Card>
</CardGroup>

## API keys

Both endpoints require an enterprise API key issued from Compliance settings. The mgmt key carries write access and implicitly includes read access, so a single mgmt key can drive the full read-then-override workflow; the audit key is read-only.

| Endpoint                                                           | Accepted key types                                        |
| ------------------------------------------------------------------ | --------------------------------------------------------- |
| [team.asset.list](/enterprise/v2/team.asset.list)                  | `KEY_TYPE_TEAM_ASSET_AUDIT` or `KEY_TYPE_TEAM_ASSET_MGMT` |
| [team.asset.update\_scope](/enterprise/v2/team.asset.update_scope) | `KEY_TYPE_TEAM_ASSET_MGMT` only                           |

The audit row records the **actual** calling key type, so list calls made with a mgmt key are still distinguishable from list calls made with an audit key. See [Authentication](/enterprise/v2/authentication) for how to issue a key.

## Asset types

| `asset_type`                       | Underlying resource                  |
| ---------------------------------- | ------------------------------------ |
| `ASSET_TYPE_SESSION_COLLABORATION` | Session-level collaboration controls |
| `ASSET_TYPE_SESSION_SHARE`         | Session share links                  |
| `ASSET_TYPE_FILE_SHARE`            | File share links                     |
| `ASSET_TYPE_WEBSITE_PUBLISH`       | Web-publish targets                  |
| `ASSET_TYPE_PROJECT_SHARE`         | Manus project shares                 |

`asset_type` is required in [team.asset.list](/enterprise/v2/team.asset.list); a single call enumerates one type. To scan everything, call the endpoint once per value.

## Share scope

The v2 API exposes a **3-value `ShareScope`** enum on every `permission` and `max_permission` field:

| `ShareScope`            | Meaning                                                        |
| ----------------------- | -------------------------------------------------------------- |
| `SHARE_SCOPE_OWNER`     | Owner-only (effectively un-shared)                             |
| `SHARE_SCOPE_TEAM_ONLY` | Restricted to team members                                     |
| `SHARE_SCOPE_PUBLIC`    | Public (semantics depends on `asset_type` — see mapping below) |

### Mapping to v1 `SharePermission`

Internally the platform stores share rows with the v1 `SharePermission` enum (`OWNER`, `TEAM_ONLY`, `PUBLIC`, `EXTERNAL`). The v2 surface collapses `PUBLIC` and `EXTERNAL` into a single `SHARE_SCOPE_PUBLIC` so callers don't have to reason about which underlying resource has a native public-link surface and which only supports invite-based external access:

| v2 `ShareScope`              | v1 `SharePermission`                                                                                                                                        | Notes                                                                                                                                                         |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SHARE_SCOPE_OWNER`          | `SHARE_PERMISSION_OWNER`                                                                                                                                    | 1:1                                                                                                                                                           |
| `SHARE_SCOPE_TEAM_ONLY`      | `SHARE_PERMISSION_TEAM_ONLY`                                                                                                                                | 1:1                                                                                                                                                           |
| `SHARE_SCOPE_PUBLIC` (write) | `SHARE_PERMISSION_PUBLIC` for `SESSION_SHARE` / `FILE_SHARE` / `WEBSITE_PUBLISH`; `SHARE_PERMISSION_EXTERNAL` for `SESSION_COLLABORATION` / `PROJECT_SHARE` | The asset\_type decides which v1 value gets persisted. Asset types with a native public link/domain land on v1.PUBLIC; invite-only types land on v1.EXTERNAL. |
| `SHARE_SCOPE_PUBLIC` (read)  | both `SHARE_PERMISSION_PUBLIC` and `SHARE_PERMISSION_EXTERNAL`                                                                                              | The response folds both v1 values back to a single `SHARE_SCOPE_PUBLIC`.                                                                                      |

When you filter [team.asset.list](/enterprise/v2/team.asset.list) with `permission=SHARE_SCOPE_PUBLIC`, only the v1 value the asset\_type writes today is matched — legacy rows that were stored with the other v1 value (e.g. an old `EXTERNAL` row on `FILE_SHARE`) will not be returned for that filter.

### Effective permission and admin override

Each share row carries two values: the share owner's chosen `permission` and an optional admin-set `max_permission` cap. The effective `permission` returned by [team.asset.list](/enterprise/v2/team.asset.list) is computed as:

* **Admin override always wins.** If an admin has explicitly set `max_permission` on the share row (i.e. it was set via the admin panel or [team.asset.update\_scope](/enterprise/v2/team.asset.update_scope)), that value is returned in `max_permission` as-is and the team's global asset controls are not applied on top.
* **Otherwise the team's global asset controls cap it.** When the share row has no admin-set `max_permission`, the team-level global control for that `asset_type` fills in `max_permission`, and the effective `permission` is the **stricter** of (raw share-row `permission`, global control).

So `max_permission` always reflects whatever ceiling currently applies — admin override if one exists, global control otherwise — and `permission` is the effective scope after that ceiling has been enforced.

## Recommended workflow: default-deny + approved exceptions

A common enterprise pattern is to keep the team's default share scope tight and use this API to mint individual exceptions after they have cleared an internal approval flow. End users never get to publish a resource publicly on their own — every approved exception lands in the audit log alongside the approval ticket.

<Steps>
  <Step title="Lock the team default to TEAM_ONLY">
    From the team admin console, set the team's global asset controls so that newly created shares default to `TEAM_ONLY`. From now on, anything users try to share is restricted to the team — even if a user marked their share row as public, [team.asset.list](/enterprise/v2/team.asset.list) will report the effective `permission` as `SHARE_SCOPE_TEAM_ONLY` until an admin lifts the cap on that specific row.
  </Step>

  <Step title="Route public-share requests through your approval system">
    When a team member needs a resource to be public (a published web app, a public file link, …), they file a request in your internal approval tool (ServiceNow, Jira, custom workflow). The ticket captures the business justification, the data-classification review, and the approver's sign-off — exactly the artifacts compliance will ask for later.
  </Step>

  <Step title="Discover the share_uid">
    Once approved, an automation (or the approver themselves) calls [team.asset.list](/enterprise/v2/team.asset.list) with the right `asset_type` and `owner_id` filter to find the `uid` of the share row.
  </Step>

  <Step title="Override to PUBLIC via the API">
    Use the `KEY_TYPE_TEAM_ASSET_MGMT` key to call [team.asset.update\_scope](/enterprise/v2/team.asset.update_scope) with `permission: SHARE_SCOPE_PUBLIC` and a `note` that includes the approval ticket ID. This sets the share row's admin override, which wins over the team's global `TEAM_ONLY` default. The audit row will carry both your `note` and the calling key's `api_key_name`, so a future audit can trace any public asset back to a specific approval.
  </Step>

  <Step title="(Optional) periodic re-attestation">
    Run a scheduled job with the `KEY_TYPE_TEAM_ASSET_AUDIT` key to enumerate every effective-`SHARE_SCOPE_PUBLIC` row, cross-reference against your approval system's still-valid tickets, and call [team.asset.update\_scope](/enterprise/v2/team.asset.update_scope) to revert anything whose approval has expired or been revoked.
  </Step>
</Steps>

## Operational notes

* **Audit logging.** Every call (success or failure, including auth failures) writes one row to the enterprise key audit log and one row to the API query log. The `note` you pass to `team.asset.update_scope` lands in `team_asset_audit_logs.remark`. Operators reviewing the team asset audit log can tell API-driven overrides apart from manual admin-panel actions via the `api_key_name` field on each entry: **unset** means a real human acting from the admin UI, **set to the calling key's name** means an API call, and **set but empty** means an API call where the underlying key has since been deleted.
* **Tightening vs. loosening.** When the new permission is stricter than the current one (for example `SHARE_SCOPE_PUBLIC → SHARE_SCOPE_OWNER`), the underlying resource is tightened first, then the database row is updated. If the second step fails, the system is over-restrictive but never under-restrictive. The reverse direction (loosening) updates the database first; same fail-safe property applies.
* **Stale shares.** If the underlying session / file / web-publish was deleted but the share row remains, [team.asset.list](/enterprise/v2/team.asset.list) returns it with `asset_exists: false` and [team.asset.update\_scope](/enterprise/v2/team.asset.update_scope) returns `internal` because there is no underlying resource to propagate to.
* **Pagination.** Offset-based: `limit` defaults to 100, max 1000; `offset` defaults to 0.