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

# Share and control access

> Make artifacts public, private, email-allowlisted, or accessible through scoped share links.

Artifacts supports quick public sharing and stricter controls for private work. Every change runs through the same authorization layer and is recorded in audit history.

## Read current access

<CodeGroup>
  ```bash CLI theme={"theme":"github-dark"}
  artifacts artifact access get --artifact-id ARTIFACT_ID
  ```

  ```text REST theme={"theme":"github-dark"}
  GET /api/artifacts/:artifactId/access
  ```

  ```json MCP theme={"theme":"github-dark"}
  {
    "tool": "get_artifact_access",
    "input": { "artifactId": "ARTIFACT_ID" }
  }
  ```
</CodeGroup>

## Set who can see it

Access is controlled by two switches plus an optional email allowlist. The CLI takes the whole access object as JSON:

<Tabs>
  <Tab title="Public">
    Anyone with the URL can view it.

    ```bash theme={"theme":"github-dark"}
    artifacts artifact access set \
      --artifact-id ARTIFACT_ID \
      --json '{"publicView":true,"publicEdit":false,"viewerEmails":[]}'
    ```
  </Tab>

  <Tab title="Private">
    Only owners, workspace members, allowlisted emails, authorized keys, or share links can view it.

    ```bash theme={"theme":"github-dark"}
    artifacts artifact access set \
      --artifact-id ARTIFACT_ID \
      --json '{"publicView":false,"publicEdit":false,"viewerEmails":[]}'
    ```

    <Info>Private artifacts require a plan with private artifact entitlements.</Info>
  </Tab>

  <Tab title="Email allowlist">
    Named people sign in with a verified, matching email.

    ```bash theme={"theme":"github-dark"}
    artifacts artifact access set \
      --artifact-id ARTIFACT_ID \
      --json '{"publicView":false,"publicEdit":false,"viewerEmails":["teammate@example.com"]}'
    ```
  </Tab>
</Tabs>

## Share links

Share links grant one role for a single artifact, and can expire. Use `editor` only when the recipient should be able to update the artifact.

<CodeGroup>
  ```bash Create theme={"theme":"github-dark"}
  artifacts share create \
    --artifact-id ARTIFACT_ID \
    --role viewer \
    --expires-at 2026-06-30T12:00:00.000Z
  ```

  ```bash List theme={"theme":"github-dark"}
  artifacts share list --artifact-id ARTIFACT_ID
  ```

  ```bash Revoke theme={"theme":"github-dark"}
  artifacts share revoke --share-link-id SHARE_LINK_ID
  ```
</CodeGroup>

The matching REST routes:

```text theme={"theme":"github-dark"}
POST /api/artifacts/:artifactId/share-links
GET  /api/artifacts/:artifactId/share-links
POST /api/share-links/:shareLinkId/revoke
```

Revoking stops future access through that link while keeping audit records intact.

## Review audit events

<CodeGroup>
  ```bash Artifact theme={"theme":"github-dark"}
  artifacts audit list --artifact-id ARTIFACT_ID --limit 50
  ```

  ```bash Workspace theme={"theme":"github-dark"}
  artifacts workspace audit --workspace-id WORKSPACE_ID --limit 50
  ```
</CodeGroup>

Audit retention depends on your plan:

| Plan | Retention |
| ---- | --------- |
| Free | 7 days    |
| Pro  | 90 days   |
| Team | 365 days  |

## Patterns that work well

* **Public view** for artifacts you'll paste into issues, pull requests, or docs.
* **Private + email allowlist** for specific teammates.
* **Expiring viewer share links** for ad hoc review.
* **Editor share links** sparingly — revoke them once the collaboration window closes.
* **Narrowly scoped API keys** for automation.