# Organizations

Source: https://heaven.dev/docs/organizations

An organization shares one balance, its pools, Computers and integrations among its members and teams.

Besides your personal account, you can belong to up to 10 organizations. To act in one, name it with `"organization"` in any request. If you belong to only one, the organization's own commands can leave it out. Joining or creating an organization moves nothing out of your personal account.

Read with `GET /v1/organization/`. Change with `POST /v1/organization/modify` and one `action`, which is the command name without its `organization` prefix: `organization member add` is `"member add"`. Name a person by email address or user ID.

## Roles

| Role | Can |
| --- | --- |
| `billing_owner` | Everything an admin can, and also hand billing ownership on and close the organization. Each organization has one. |
| `admin` | Manage all of the organization's pools, money and Computers, and its members and teams. |
| `user` | Create Computers in the organization's pools and manage their own. |

A member's `grants` add management commands on top of their role, across the organization. For example, you can grant a user `pool start` and `pool stop`. `withholds` take commands away, such as an admin without `pool delete`. Nobody can give more than they hold.

These lists can't name:

- `exec`, `terminal`, `logs` or `export`, since access inside a Computer comes from a role;
- commands that change the organization or your membership;
- commands that act only in a person's own account, such as `api-key create`.

A command both granted and withheld is refused. Withholding a command also withholds the commands that need it: without `delete`, a member can't `reset` either. Responses that show `grants` also show `grant_scope: "organization"`, since a grant reaches every Computer and pool in the organization.

## Your organizations

### Read your organizations

`GET /v1/organization/`

Lists your organizations, each with your role, or returns one with its settings, members and teams.

#### Query

- `organization` string: Read this organization: its members and teams.

- An API key needs `organization view` in its commands.

Request:

```sh
curl 'https://heaven.dev/v1/organization/?organization=acme' \
  -H "Authorization: Bearer $HEAVEN_API_KEY"
```

200:

```json
{
  "version": 1,
  "data": {
    "id": "cbc818f1-cb0e-4738-bab6-8824b8c758d5",
    "name": "acme",
    "role": "billing_owner",
    "computer_sharing": "all-members",
    "outsider_invitations": "team-admins",
    "members": [
      {
        "user_id": "a308210e-005c-43ba-b452-db81b4034d90",
        "email": "you@example.com",
        "role": "billing_owner",
        "teams": ["web"]
      }
    ],
    "teams": [ … ]
  }
}
```

### Read usage

`GET /v1/organization/?view=usage`

Returns this month's capacity, storage and pool use, with their charges. For the billing owner and admins.

The response lists each capacity purchase with its charges, and each pool's hours, CPU, traffic and storage.

#### Query

- `organization` string: Act in this organization (its name or ID) instead of your personal account.

- An API key needs `organization usage` in its commands.

Request:

```sh
curl 'https://heaven.dev/v1/organization/?view=usage' \
  -H "Authorization: Bearer $HEAVEN_API_KEY"
```

### Create an organization

`POST /v1/organization/create`

Creates an organization with you as its billing owner.

#### Body

- `name` string *required*: The organization's name, unique across Heaven and compared without case. A taken name returns `conflict`.

- API keys you create can't run it. Use a sign-in key or SSH.

Request:

```sh
curl https://heaven.dev/v1/organization/create \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"name": "acme"}'
```

200:

```json
{"version": 1, "data": {"id": "cbc818f1-cb0e-4738-bab6-8824b8c758d5", "name": "acme"}}
```

## Members

### List members

`GET /v1/organization/?view=members`

Lists the organization's members, each with their role and any commands granted or withheld.

#### Query

- `organization` string: Act in this organization (its name or ID) instead of your personal account.

- An API key needs `organization member view` in its commands.

Request:

```sh
curl 'https://heaven.dev/v1/organization/?view=members' \
  -H "Authorization: Bearer $HEAVEN_API_KEY"
```

### Invite a member

`POST /v1/organization/modify` with `"action": "member add"`

Invites a person as a user, an admin or the billing owner. You can also grant or withhold commands, and name teams for them to join.

The person needs a Heaven account. When they accept, they also join `teams`.

#### Body

- `user` string *required*: The person's email address or user ID.
- `role` string: Their role: user (the default), admin or billing_owner.
- `grants` string[]: A command granted beyond their role, over every Computer and pool of the organization.
- `withholds` string[]: A command withheld from their role.
- `teams` string[]: A team they also join on accepting.
- `organization` string: Act in this organization (its name or ID) instead of your personal account.

- API keys you create can't run it. Use a sign-in key or SSH.

Request:

```sh
curl https://heaven.dev/v1/organization/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "member add", "user": "ana@example.com", "role": "user", "grants": ["pool start", "pool stop"], "teams": ["web"], "organization": "acme"}'
```

### Change a member's access

`POST /v1/organization/modify` with `"action": "member role"`

Sets a member's role, grants and withholds in one request.

A list you leave out becomes empty. `billing_owner` offers billing ownership, which moves only when they accept. The offer ends after 7 days, when they decline it (`invitation decline`), or when you cancel it.

#### Body

- `user` string *required*: The member: email address or user ID.
- `role` string: user, admin or billing_owner. Without it, they keep their role.
- `grants` string[]: A command granted beyond their role, over every Computer and pool of the organization.
- `withholds` string[]: A command withheld from their role.
- `organization` string: Act in this organization (its name or ID) instead of your personal account.

- API keys you create can't run it. Use a sign-in key or SSH.

Request:

```sh
curl https://heaven.dev/v1/organization/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "member role", "user": "ada@example.com"}'
```

### Remove a member

`POST /v1/organization/modify` with `"action": "member remove"`

Removes a member, or cancels their invitation. Their Computers go to the organization, or to a member or team you name.

#### Body

- `user` string *required*: The member, or the invitation's email address.

- `transfer_computers_to` object

  One of `{"user": "ana@example.com"}`, `{"team": "web"}` or `{"organization": true}`.

  - `user` string: A member who gets their Computers.
  - `team` string: Their Computers go to this team.
  - `organization` boolean: Their Computers go to the organization (the default).

- `organization` string: Act in this organization (its name or ID) instead of your personal account.

- `keep_shares` boolean: Keep shares with people, teams and the organization that the new owner could make themselves; without it, shares are cleared.

- API keys you create can't run it. Use a sign-in key or SSH.

Request:

```sh
curl https://heaven.dev/v1/organization/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "member remove", "user": "ada@example.com"}'
```

### List sent invitations

`GET /v1/organization/?view=invitations`

Lists the pending invitations the organization and its teams have sent. For the billing owner and admins.

#### Query

- `organization` string: Act in this organization (its name or ID) instead of your personal account.

- An API key needs `organization invitation view` in its commands.

Request:

```sh
curl 'https://heaven.dev/v1/organization/?view=invitations' \
  -H "Authorization: Bearer $HEAVEN_API_KEY"
```

### Cancel an invitation

`POST /v1/organization/modify` with `"action": "invitation cancel"`

Withdraws a pending invitation to the organization or one of its teams.

#### Body

- `invitation` string *required*: The invitation's ID, or the person's email or ID.
- `organization` string: Act in this organization (its name or ID) instead of your personal account.

- API keys you create can't run it. Use a sign-in key or SSH.

Request:

```sh
curl https://heaven.dev/v1/organization/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "invitation cancel", "invitation": "INVITATION"}'
```

## Teams

A team is a named group of an organization's members, so you can give access to the whole group. A team's `admin`s manage its members, and its `member`s get what the team is given. Outside the organization, a team is named `ORGANIZATION@TEAM`. When you share a Computer with a team (`share add` with `team`), access follows the team as people join and leave.

### List teams

`GET /v1/organization/?view=teams`

Lists the organization's teams, or returns one team with its members and the Computers it owns.

#### Query

- `team` string: Read this team: its members and the Computers it owns.
- `organization` string: Act in this organization (its name or ID) instead of your personal account.

- An API key needs `organization team view` in its commands.

Request:

```sh
curl 'https://heaven.dev/v1/organization/?view=teams' \
  -H "Authorization: Bearer $HEAVEN_API_KEY"
```

### Create a team

`POST /v1/organization/modify` with `"action": "team create"`

Creates a team of the organization's members.

#### Body

- `name` string *required*: The team's name, unique in the organization.
- `users` string[]: A member to put in it.
- `organization` string: Act in this organization (its name or ID) instead of your personal account.

- API keys you create can't run it. Use a sign-in key or SSH.

Request:

```sh
curl https://heaven.dev/v1/organization/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "team create", "name": "web", "organization": "acme"}'
```

200:

```json
{
  "version": 1,
  "data": {
    "id": "bf7edc39-c078-43c7-92e6-364e27d70f21",
    "name": "web",
    "full_name": "acme@web",
    "member_access": "root",
    "members": [],
    "computers": [],
    "shares": [],
    "pools": []
  }
}
```

### Rename a team

`POST /v1/organization/modify` with `"action": "team rename"`

Gives a team a new name.

#### Body

- `team` string *required*: A team: TEAM, or ORGANIZATION@TEAM outside it.
- `name` string *required*: The team's new name.
- `organization` string: Act in this organization (its name or ID) instead of your personal account.

- API keys you create can't run it. Use a sign-in key or SSH.

Request:

```sh
curl https://heaven.dev/v1/organization/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "team rename", "team": "TEAM", "name": "NAME"}'
```

### Change a team's setting

`POST /v1/organization/modify` with `"action": "team setting"`

Sets what the team's members get on the Computers it owns: root, web or no access.

#### Body

- `team` string *required*: A team: TEAM, or ORGANIZATION@TEAM outside it.
- `setting` string *required*: The setting to change: member-access.
- `value` string *required*: For `member-access`: `root` (the default), `web` or `none`.
- `organization` string: Act in this organization (its name or ID) instead of your personal account.

- API keys you create can't run it. Use a sign-in key or SSH.

Request:

```sh
curl https://heaven.dev/v1/organization/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "team setting", "team": "TEAM", "setting": "SETTING", "value": "VALUE"}'
```

### Add a team member

`POST /v1/organization/modify` with `"action": "team member add"`

Adds a member of the organization to a team, or invites someone from outside who joins that team only.

Add them as a `member` or an `admin`. Someone from outside the organization gets an invitation and joins as a `user` in that team only.

#### Body

- `team` string *required*: A team: TEAM, or ORGANIZATION@TEAM outside it.
- `user` string *required*: A person: email address or user ID.
- `role` string: Their team role: member (the default) or admin.
- `organization` string: Act in this organization (its name or ID) instead of your personal account.

- API keys you create can't run it. Use a sign-in key or SSH.

Request:

```sh
curl https://heaven.dev/v1/organization/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "team member add", "team": "TEAM", "user": "ada@example.com"}'
```

### Change a team member's role

`POST /v1/organization/modify` with `"action": "team member role"`

Makes a team member an admin or a member.

#### Body

- `team` string *required*: A team: TEAM, or ORGANIZATION@TEAM outside it.
- `user` string *required*: A person: email address or user ID.
- `role` string *required*: Their new team role: admin or member.
- `organization` string: Act in this organization (its name or ID) instead of your personal account.

- API keys you create can't run it. Use a sign-in key or SSH.

Request:

```sh
curl https://heaven.dev/v1/organization/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "team member role", "team": "TEAM", "user": "ada@example.com", "role": "ROLE"}'
```

### Remove a team member

`POST /v1/organization/modify` with `"action": "team member remove"`

Takes a member out of a team, or cancels their invitation to it. They stay in the organization.

#### Body

- `team` string *required*: A team: TEAM, or ORGANIZATION@TEAM outside it.
- `user` string *required*: A person: email address or user ID.
- `organization` string: Act in this organization (its name or ID) instead of your personal account.

- API keys you create can't run it. Use a sign-in key or SSH.

Request:

```sh
curl https://heaven.dev/v1/organization/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "team member remove", "team": "TEAM", "user": "ada@example.com"}'
```

### Leave a team

`POST /v1/organization/modify` with `"action": "team leave"`

Takes you out of a team. You stay in the organization.

#### Body

- `team` string *required*: A team: TEAM, or ORGANIZATION@TEAM outside it.
- `organization` string: Act in this organization (its name or ID) instead of your personal account.

- API keys you create can't run it. Use a sign-in key or SSH.

Request:

```sh
curl https://heaven.dev/v1/organization/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "team leave", "team": "TEAM"}'
```

### Delete a team

`POST /v1/organization/modify` with `"action": "team delete"`

Deletes a team. Its members stay in the organization, and its Computers go to the organization.

#### Body

- `team` string *required*: A team: TEAM, or ORGANIZATION@TEAM outside it.
- `organization` string: Act in this organization (its name or ID) instead of your personal account.

- API keys you create can't run it. Use a sign-in key or SSH.

Request:

```sh
curl https://heaven.dev/v1/organization/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "team delete", "team": "TEAM"}'
```

## Settings and leaving

### Rename the organization

`POST /v1/organization/modify` with `"action": "rename"`

Gives the organization a new name.

#### Body

- `name` string *required*: The new name, unique across Heaven.
- `organization` string: Act in this organization (its name or ID) instead of your personal account.

- API keys you create can't run it. Use a sign-in key or SSH.

Request:

```sh
curl https://heaven.dev/v1/organization/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "rename", "name": "NAME"}'
```

### Change a setting

`POST /v1/organization/modify` with `"action": "setting"`

Sets who can share the organization's Computers, and who can invite outsiders into its teams.

#### Body

- `setting` string *required*: The setting to change: computer-sharing or outsider-invitations.
- `value` string *required*: For `computer-sharing`: `admins-only` or `all-members`. For `outsider-invitations`, who can invite people from outside into a team: `team-admins` (the default) or `admins-only`.
- `organization` string: Act in this organization (its name or ID) instead of your personal account.

- API keys you create can't run it. Use a sign-in key or SSH.

Request:

```sh
curl https://heaven.dev/v1/organization/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "setting", "setting": "computer-sharing", "value": "admins-only", "organization": "acme"}'
```

### Leave the organization

`POST /v1/organization/modify` with `"action": "leave"`

Takes you out of the organization. Your Computers in it go to the organization, or to a member or team you name.

The billing owner can leave only after handing billing ownership to someone else.

#### Body

- `transfer_computers_to` object

  One of `{"user": "ana@example.com"}`, `{"team": "web"}` or `{"organization": true}`.

  - `user` string: A member who gets your Computers.
  - `team` string: Your Computers go to this team.
  - `organization` boolean: Your Computers go to the organization (the default).

- `organization` string: Act in this organization (its name or ID) instead of your personal account.

- `keep_shares` boolean: Keep shares with people, teams and the organization that the new owner could make themselves; without it, shares are cleared.

- API keys you create can't run it. Use a sign-in key or SSH.

Request:

```sh
curl https://heaven.dev/v1/organization/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "leave"}'
```

## Closing an organization

### Close the organization

`POST /v1/organization/delete`

Closes the organization. Only the billing owner can close it. Without `yes`, it only shows what closing would do.

If the organization has other members, it closes a week later (`closes_at`), and each member gets an email at once. Otherwise it closes at once (`closed`).

When it closes, the other members are removed, invitations are canceled and teams are deleted. Its paid monthly plans end with their paid month, and its pools, Computers and balance move to your personal account.

#### Body

- `yes` boolean: Confirm. Without it, nothing changes, and the response (`invalid`) says who would be removed and what would move. With `true`, the organization closes, or starts its week's notice.
- `cancel` boolean: With `true`, keep an organization that's closing. Its members are told.
- `organization` string: Act in this organization (its name or ID) instead of your personal account.

- API keys you create can't run it. Use a sign-in key or SSH.

Request:

```sh
curl https://heaven.dev/v1/organization/delete \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"yes": true, "organization": "acme"}'
```