# Share a Computer

URL: https://heaven.dev/docs/reference/computers/share-add
Updated: 2026-11-21

Share a Computer with specific people, a team or the whole organization. The default role grants website access. Choose root to grant SSH access or admin to also grant management access. Sharing again keeps the broader role.

`POST /v1/computer/modify`

## Parameters

- `computer` (string): Computer name or ID.
- `computers` (string[]): Computer names or IDs, supplied instead of `computer`.
- `users` (string[]): A person to share the Computer with, by email address or user ID.
- `team` (string): The team in the Computer's organization to give access to.
- `whole_organization` (boolean): Select everyone in the organization that owns the Computer.
- `role` (string): Access to grant. `web` opens the website and is the default. `root` adds SSH. `admin` adds management access. Transfer, sharing and support access stay with owners.
- `commands` (string[]): Additional management command allowed on this Computer. Give an exact command name such as `restart`.
- `message` (string): Message for the invitation email to the people being given access. Use up to 500 bytes.

## Returns

- `data` (object | object[], always present): Sharing results for each recipient and Computer.
  - `alternative-1` (object): A saved share and any access retained through other routes.
    - `commands` (string[] | null, always present): Management commands this share grants in addition to its role.
    - `hint` (string): How to reduce access retained through those other routes. May be omitted.
    - `kept` (object[]): Access the recipient still has through other routes. May be omitted.
      - `items` (object): Access retained through a route other than the share just changed.
        - `commands` (string[]): Additional management commands this route grants. May be omitted.
        - `name` (string): Role, team or pool identifying that route. May be omitted.
        - `role` (string, always present): Access role this route grants.
        - `via` (string, always present): Route granting access, such as ownership, an organization role, team or pool share.
    - `notice` (string): Sharing email's state, when a notice applies. May be omitted.
    - `role` (string, always present): Resulting access role, or `none` after removal.
    - `shared` (string, always present): Person, team or organization whose share was changed.
    - `updated` (boolean, always present): Whether this request changed the share.
  - `alternative-2` (object[]): A saved share and any access retained through other routes.
    - `items` (object): A saved share and any access retained through other routes.
      - `commands` (string[] | null, always present): Management commands this share grants in addition to its role.
      - `hint` (string): How to reduce access retained through those other routes. May be omitted.
      - `kept` (object[]): Access the recipient still has through other routes. May be omitted.
        - `items` (object): Access retained through a route other than the share just changed.
          - `commands` (string[]): Additional management commands this route grants. May be omitted.
          - `name` (string): Role, team or pool identifying that route. May be omitted.
          - `role` (string, always present): Access role this route grants.
          - `via` (string, always present): Route granting access, such as ownership, an organization role, team or pool share.
      - `notice` (string): Sharing email's state, when a notice applies. May be omitted.
      - `role` (string, always present): Resulting access role, or `none` after removal.
      - `shared` (string, always present): Person, team or organization whose share was changed.
      - `updated` (boolean, always present): Whether this request changed the share.
  - `alternative-3` (object): Results for a multi-Computer request. Each target can succeed or fail independently.
    - `request_id` (string, always present): Request ID for this multi-Computer change.
    - `results` (object[] | null, always present): Each target's accepted operation, direct result or error, in request order.
      - `items` (object): One Computer's operation, direct result or error.
        - `computer` (object, always present): Target's ID and name.
          - `id` (string, always present): Computer ID.
          - `name` (string, always present): Computer's name when this result was prepared.
        - `data` (JSON value): Direct command result, with the same meaning as a single-Computer result. May be omitted.
        - `error` (object): Reason this target could not be changed. May be omitted.
          - `action` (object): A suggested command addressing the problem. May be omitted.
            - `command` (string, always present): Command's catalog name.
            - `line` (string, always present): Complete suggested command line.
          - `kind` (string, always present): Error category. `unknown` means the effect is uncertain; reconcile before retrying.
          - `message` (string, always present): What happened and any action needed from you.
          - `operation_id` (string): Operation to read before repeating uncertain work. May be omitted.
          - `request_id` (string): Request ID identifying the change during reconciliation. May be omitted.
          - `retry_after` (integer): Seconds before retrying a rate-limited request or a refused wait. May be omitted.
          - `url` (string): Payment page for a payment-required response. May be omitted.
        - `operation` (object): Accepted operation for this target, if the command returns one. May be omitted.
          - `by` (string): Requester's email address, or user ID if no email is recorded. Omitted for your own requests. May be omitted.
          - `completed_at` (string (date-time)): When the operation reached its final state. Absent while unfinished. May be omitted.
          - `computer_id` (string, always present): Computer's stable ID.
          - `created_at` (string (date-time)): When Heaven accepted the change. May be omitted.
          - `error_code` (string): Recorded failure code. May be omitted.
          - `id` (string, always present): Operation ID for `operation view`.
          - `kind` (string, always present): Change being tracked.
          - `message` (string): An explanation of the recorded failure and any next action. May be omitted.
          - `state` (string, always present): `accepted` means saved and unfinished. `complete` means the change finished. `failed` means it could not finish. `superseded` means a newer change replaced it before completion. Values: `"accepted"`, `"complete"`, `"failed"`, `"superseded"`.

## Errors

Each code is explained in full at https://heaven.dev/docs/reference/errors.

| Code | Status | What happened |
|---|---:|---|
| `invalid` | 400 | An input is missing or invalid. |
| `unauthenticated` | 401 | The credential is missing, invalid, expired or revoked. |
| `denied` | 403 | The caller lacks permission for this action. |
| `not_found` | 404 | The resource is absent or inaccessible to this caller. |
| `conflict` | 409 | The request conflicts with the current resource state or an earlier request. |
| `over_capacity` | 409 | The request exceeds a resource or credential allowance. |
| `access_list_full` | 409 | The change would exceed the access-list allowance. |
| `payment_required` | 402 | Payment or credit is required. |
| `rate_limited` | 429 | The caller's request rate exceeds its limit. |
| `busy` | 429 | Too much work is in progress to accept this request. |
| `unknown` | 503 | The outcome is unconfirmed; a change may have happened. |
| `unavailable` | 503 | The service or requested feature is unavailable. |

## Notes

- CLI: `heaven login` with `HEAVEN_API_KEY` unset. MCP: Heaven sign-in. cURL: `HEAVEN_SIGN_IN_KEY` from approved device sign-in (`POST /v1/auth/create`).
- A key limited to a command list cannot run this command.
- Use `computers` instead of `computer` for several targets, each with its own result.
- **People:** Grant access to people by email address. Required: `users`. Optional: `computer`, `computers`, `role`, `commands`, `message`.
- **Team:** Grant access to a team in the Computer's organization. Required: `team`. Optional: `computer`, `computers`, `role`, `commands`, `message`.
- **Organization:** Grant access to every member of the Computer's organization. Required: `whole_organization`. Optional: `computer`, `computers`, `role`, `commands`, `message`.

## Examples

```sh tab="heaven CLI"
heaven share add COMPUTER
  [--user USER ...]
  [--team TEAM]
  [--whole-organization]
  [--role ROLE]
  [--command COMMAND ...]
  [--message MESSAGE]
```

```sh tab="SSH"
ssh cli@heaven.dev share add COMPUTER
  [--user USER ...]
  [--team TEAM]
  [--whole-organization]
  [--role ROLE]
  [--command COMMAND ...]
  [--message MESSAGE]
```

```sh tab="cURL"
curl https://heaven.dev/v1/computer/modify \
  -H "Authorization: Bearer $HEAVEN_SIGN_IN_KEY" \
  --json '{"action": "share add", "computer": "my-site", "users": ["ada@example.com"], "role": "root"}'
```

```json tab="MCP"
{ "tool": "share_add",
  "arguments": { "computer": "my-site", "users": ["ada@example.com"], "role": "root" } }
```

Response:

```json title="Response excerpt"
{
  "version": 1,
  "data": {
    "commands": [],
    "notice": "queued",
    "role": "root",
    "shared": "ada@example.com",
    "updated": true
  }
}
```
