Endpoints

Integrations

Integrations let Computers call an outside service without its secret ever being on them.

Give Heaven a service's credential once. Attached Computers then call the service through Heaven's proxy, which adds the credential to each request, so the secret is never on the Computer. Inside a Computer, an integration named payments is at http://payments.int.heaven.dev (or https://):

Inside the Computer

curl http://payments.int.heaven.dev/v1/items
# reaches https://api.example.com/v1/items, with the stored credential

Term	Means
`kind`	`http-proxy` for an HTTPS API, `registry` for a private container registry, `github` for GitHub
`target`	The service's HTTPS origin, such as `https://api.example.com` (not for GitHub)
`attachments`	Which Computers can use it: `computer:NAME`, `pool:POOL` (the Computers in it, including new ones), `tag:TAG` or `auto:all`

The account's owner, or an organization's admins, change integrations. Other members see them with secrets masked.

Adding a tag that a tag: attachment selects gives a Computer the credential. So only the owner or admins can add such a tag to a Computer, signed in or over SSH. An API key is refused (denied). Anyone with root on an attached Computer can use the integration, so attach it only where that's acceptable.

Every account starts with self, which returns a Computer's own metadata at https://self.int.heaven.dev/.

Read with GET /v1/integration/. Change one with POST /v1/integration/modify, naming the integration and an action. The action is the command name without its integration prefix.

Managing integrations

List integrations

GET/v1/integration/

Lists your account's integrations, with their credentials masked.

Stored credentials show as ***. A GitHub integration that needs to be connected again shows reconnect.

Query

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

An API key needs integration view in its commands.

Request

curl 'https://heaven.dev/v1/integration/' \
  -H "Authorization: Bearer $HEAVEN_API_KEY"

200

{
  "version": 1,
  "data": [
    {
      "id": "aaf026c7-c320-4e46-87fe-e054afa52f93",
      "name": "self",
      "type": "self",
      "attachments": ["auto:all"]
    },
    {
      "id": "0fa26014-a995-4109-80f0-db2136c9303a",
      "name": "payments",
      "type": "http-proxy",
      "target": "https://api.example.com",
      "strip_prefix": "",
      "comment": "",
      "attachments": ["tag:web"],
      "headers": { "Authorization": "Bearer ***" }
    }
  ]
}

Create an integration

POST/v1/integration/create

Stores an HTTPS service's credential. Attached Computers use it through Heaven's proxy without ever holding it. Kind github connects your GitHub account with a device code instead.

Body

kind string required: http-proxy or registry. For GitHub, see GitHub.
name string: The integration's name: 1 to 63 lowercase letters, digits and hyphens, unique in the account. It becomes NAME.int.heaven.dev.
target string: The service's HTTPS origin. It can include a port, but no path.
headers string[]: Other headers to add, as Name:value, up to 16.
bearer string: A token sent as Authorization: Bearer ….
basic_auth string: USER:PASSWORD, sent as basic authentication.
strip_prefix string: A path prefix to remove before forwarding, such as /api/v3.
attachments string[]: What uses it: computer:NAME, pool:POOL, tag:TAG or auto:all.
comment string: A note, shown to Computers in their metadata.
peer boolean: The target is another of your Computers, https://NAME.heaven.dev, on port 443 or 3000 to 9999. You need ownership or root access on it. Heaven vouches for each request: the target receives X-Heaven-Source-Vm with the caller's name, which callers can't forge. The integration keeps working when the target is renamed. Once the target is deleted, view shows target_deleted.
no_auth boolean: Store no credential, and forward requests as they are. Can't be used with peer.
read_only boolean: For GitHub integrations only. With true, the integration's writes are refused.
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/integration/create \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{
    "kind": "http-proxy",
    "name": "payments",
    "target": "https://api.example.com",
    "bearer": "sk_live_…",
    "attachments": ["tag:web"]
  }'

200

{"version": 1, "data": {"id": "0fa26014-a995-4109-80f0-db2136c9303a"}}

Change an integration

POST/v1/integration/modify"action": "edit"

Changes an integration's target, credential or settings. A credential is replaced only when given.

Changing target drops the stored credential, so send it again, or send no_auth. A GitHub integration takes only read_only, reconnect and comment.

Body

integration string required: An integration's name.
target string: The service's HTTPS address.
headers string[]: A header the service needs, NAME: VALUE. Treated as a secret and never included in errors.
bearer string: The service's bearer token. Treated as a secret and never included in errors.
basic_auth string: The service's user:password. Treated as a secret and never included in errors.
strip_prefix string: A path prefix to remove before calling the service.
attachments string[]: Also attach it to computer:NAME, pool:POOL, tag:TAG or auto:all. Its other attachments stay: integration detach removes one.
comment string: A comment on it.
peer boolean: Make it a peer integration. target is a Computer's website (https://NAME.DOMAIN), which attached Computers call as themselves. Heaven keeps the key that signs their calls.
no_auth boolean: The service needs no credential. Computers reach it through Heaven's proxy with none added, and edit clears the stored one.
read_only boolean: For GitHub integrations only. With true, the integration's writes are refused.
reconnect boolean: Start over with a new device code.
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/integration/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "edit", "integration": "INTEGRATION"}'

Attach an integration

POST/v1/integration/modify"action": "attach"

Lets a Computer, the Computers with a tag, or every Computer use an integration.

Body

integration string required: An integration's name.
attachment string required: What can use it: computer:NAME, pool:POOL, tag:TAG or auto:all.
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/integration/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "attach", "integration": "payments", "attachment": "computer:my-site"}'

Detach an integration

POST/v1/integration/modify"action": "detach"

Takes an integration away from a Computer, a tag or every Computer.

Body

integration string required: An integration's name.
attachment string required: What to detach it from: computer:NAME, pool:POOL, tag:TAG or auto:all.
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/integration/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "detach", "integration": "INTEGRATION", "attachment": "ATTACHMENT"}'

Delete an integration

POST/v1/integration/delete

Deletes an integration and its stored credential. Computers can no longer use it.

For GitHub, this forgets the token. It doesn't uninstall Heaven's app on GitHub.

Body

integration string required: An integration's 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/integration/delete \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"integration": "INTEGRATION"}'

GitHub

Connect your own GitHub account, and git clone and gh work on attached Computers with no token copied there. Send POST /v1/integration/create with "kind": "github". The integration acts as you on GitHub: it can do what you can, in the repositories you choose, and no more.

Any member can connect their own GitHub account and attach it to Computers they own. Only the account's owner or an organization's admins can attach one with pool:, tag: or auto:all, or to other members' Computers.

Ask for a code
Send {"kind":"github","name":"github-me"}. The response has a GitHub device code and two links, valid for an hour. One link authorizes Heaven, and the other picks the repositories it can reach.
Enter the code
Enter it at https://github.com/login/device, then open the links.
Send the same request again
Heaven waits up to 20 seconds for GitHub, then connects. If you send it too early, the response says so and keeps the code.

Request

curl https://heaven.dev/v1/integration/create \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"kind": "github", "name": "github-me", "attachments": ["computer:my-site"]}'

On a Computer, git clone https://github.int.heaven.dev/OWNER/REPO works. So does gh, with GH_HOST=github.int.heaven.dev and any GH_ENTERPRISE_TOKEN value, which Heaven replaces with your credential. github.int uses the attached GitHub integration that reaches the repository's owner. With read_only: true, every write is refused. To create a Computer with a repository already cloned, send github: {"repo": "OWNER/REPO"} to create.

Then, on the Computer

git clone https://github.int.heaven.dev/acme/website
GH_HOST=github.int.heaven.dev GH_ENTERPRISE_TOKEN=x gh pr list

When GitHub access is revoked, or after six months without use, the list shows reconnect. Send edit with reconnect: true to get a new code. The attachments stay.

List a GitHub integration's repositories

GET/v1/integration/?view=repos

Lists the repositories a GitHub integration reaches.

Query

integration string required: An integration's name.
organization string: Act in this organization (its name or ID) instead of your personal account.

An API key needs integration repo view in its commands.

Request

curl 'https://heaven.dev/v1/integration/?integration=github-me&view=repos' \
  -H "Authorization: Bearer $HEAVEN_API_KEY"

Integrations

Managing integrations

List integrations

Query

Create an integration

Body

Change an integration

Body

Attach an integration

Body

Detach an integration

Body

Delete an integration

Body

GitHub

Ask for a code

Enter the code

Send the same request again

List a GitHub integration's repositories

Query