Skip to content

Create an integration

Create an HTTPS proxy, registry or GitHub integration, or restore the built-in self integration. Heaven keeps the stored upstream credential outside the Computers that use it. GitHub requires authorization through the returned link or device flow before the integration is ready.

Parameters

#
kindstringRequired
Integration type. http-proxy forwards to an HTTPS service. registry authenticates to a container registry. github starts GitHub authorization. self restores the built-in Computer metadata service.
namestring
Name for an HTTPS proxy, registry or GitHub integration. Use 1 to 63 lowercase letters, digits and hyphens, starting and ending with a letter or digit. The built-in self integration keeps its fixed name.
targetstring
Upstream HTTPS origin for a proxy or registry, such as https://api.example.com. Include no path, query or credentials.
headersstring[]
Request header for the service, in NAME: VALUE form. Treated as a secret and never included in errors.
bearerstring
Bearer token for the service. Treated as a secret and never included in errors.
basic_authstring
Upstream login in USERNAME:PASSWORD form on one line. Required for a registry integration. Treated as a secret and never included in errors.
strip_prefixstring
URL path prefix to remove before forwarding requests, such as /v1.
attachmentsstring[]
Computers allowed to use the integration. Use computer:NAME, pool:POOL, tag:TAG or auto:all. Omit to create without attachments.
commentstring
Integration comment, one line of at most 200 bytes.
peerboolean
Forward to the private Computer website given by target. You need owner or root access to that Computer. Attached Computers authenticate with their own identities.
no_authboolean
Send requests without adding credentials. Clears stored credentials when editing an integration.
read_onlyboolean
Block writes (GitHub integrations only).
organizationstring
Organization name or ID. A credential, named resource or sole membership can select the organization for you.

Returns

#
dataobjectAlways present
A created integration, a pending GitHub authorization, or a completed GitHub connection.
Show 3 attributesHide attributes
alternative-1object
The integration affected by this request.
Show 5 attributesHide attributes
addressstring
Address attached Computers use to call the integration. May be omitted.
detachedboolean
Whether detaching removed any of the attachments named. May be omitted.
idstringAlways present
Integration ID.
not_attachedstring[]
Attachments named to detach that it did not have. May be omitted.
pausedboolean
Whether the integration is now paused. May be omitted.
alternative-2object
Authorization needed to connect a GitHub integration.
Show 6 attributesHide attributes
deviceobject
Code and GitHub page for the device authorization flow, when available. May be omitted.
Show 4 attributesHide attributes
codestringAlways present
Code to enter at GitHub.
expiresstring (date-time)Always present
When the device code expires.
urlstringAlways present
GitHub page where you enter the code.
waitingboolean
Whether the command was repeated before authorization completed. May be omitted.
expiresstring (date-time)Always present
When the browser connection request expires.
idstringAlways present
Integration being connected.
install_urlstringAlways present
Page to install the GitHub app on another account or organization.
notestring
Why no device code is available, when GitHub could not start that flow. May be omitted.
urlstringAlways present
Browser connection page, used while signed in to Heaven.
alternative-3object
The GitHub integration after authorization completed.
Show 5 attributesHide attributes
github_userstringAlways present
GitHub user the integration acts as.
idstringAlways present
Connected integration's ID.
install_urlstring
Page to install the app on another account or organization. May be omitted.
namestringAlways present
Integration name.
ownersstring[] | nullAlways present
GitHub installation owners accessible through the connection.

Errors

#
CodeStatusWhat happened
invalid400An input is missing or invalid.
unauthenticated401The credential is missing, invalid, expired or revoked.
denied403The caller lacks permission for this action.
not_found404The resource is absent or inaccessible to this caller.
conflict409The request conflicts with the current resource state or an earlier request.
over_capacity409The request exceeds a resource or credential allowance.
access_list_full409The change would exceed the access-list allowance.
payment_required402Payment or credit is required.
rate_limited429The caller's request rate exceeds its limit.
busy429Too much work is in progress to accept this request.
unknown503The outcome is unconfirmed; a change may have happened.
unavailable503The 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.