Endpoints

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

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

200

{
  "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

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

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

200

{"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

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

Invite a member

POST/v1/organization/modify"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

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"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

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"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

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

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

Cancel an invitation

POST/v1/organization/modify"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

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 admins manage its members, and its members 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

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

Create a team

POST/v1/organization/modify"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

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

200

{
  "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"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

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"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

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"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

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"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

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"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

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"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

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"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

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"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

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"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

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"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

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

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