Skip to content

Change an integration

Change an integration's target, credentials or settings. Changing the target discards any stored credentials. For a credentialed target change, supply replacements or explicitly remove the authentication. Use reconnect: true to renew GitHub authorization.

Parameters

#
integrationstringRequired
Integration name in the selected account.
targetstring
New upstream HTTPS origin for a proxy or registry. Include no path, query or credentials. Changing the target clears stored credentials.
headersstring[]
Request header to replace, in NAME: VALUE form. Other headers are retained. Treated as a secret and never included in errors.
remove_headersstring[]
Stored request header to stop sending, by header name such as Authorization.
bearerstring
Bearer token for the service. Treated as a secret and never included in errors.
basic_authstring
Service credential in USERNAME:PASSWORD form. Treated as a secret and never included in errors.
strip_prefixstring
URL path prefix to remove before forwarding, such as /v1. Omit to keep the existing prefix. An empty value clears it.
attachmentsstring[]
Additional Computers to grant access for a proxy or registry. Use computer:NAME, pool:POOL, tag:TAG or auto:all.
commentstring
Replacement comment, one line of at most 200 bytes. Empty clears it; omission keeps it.
peerboolean
Forward to the private Computer website given by target. You need owner or root access to that Computer.
no_authboolean
Send requests without adding credentials. Clears stored credentials when editing an integration.
read_onlyboolean
Block writes (GitHub integrations only).
reconnectboolean
Start a new authorization flow for a GitHub integration. The response includes a link and, when available, a device code. Send any other settings changes in a separate edit.
organizationstring
Organization name or ID. A credential, named resource or sole membership can select the organization for you.

Returns

#
dataobjectAlways present
An updated 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.