> ## Documentation Index
> Fetch the complete documentation index at: https://craftspace.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Connections

> How Craftspace reaches your other tools without holding your tokens in the open.

A **connection** is one authenticated link to an outside tool, owned by the member who created it and
shared with the org by grant. It carries a tool access level, so a connection can be read-only to everyone
else even when its owner can write.

## The gateway

Vendor tokens are never handled by the application code that wants them. They are encrypted with a sealed
box, and the only code that can open one is a gateway module that imports nothing else in the app. The
gateway runs in-process on loopback in every install, cloud and self-hosted alike. It is not optional: if
it fails to start, every connection path fails with it.

<Warning>
  The sealing key lives in the same database as the sealed credentials. That trade was made knowingly when
  the gateway stopped being a separate container, and it is why a database dump has to be treated as a full
  credential compromise. See [backup](/self-hosting/backup-and-upgrade).
</Warning>

## Vendor OAuth clients

Some vendors, GitHub, Google and HubSpot among them, refuse dynamic client registration and require a
callback URL registered in advance. A self-hosted install cannot add its own callback to somebody else's
OAuth app, so there are two ways to go:

1. **Register your own apps** and paste the client id and secret into server settings. Fully independent.
2. **Borrow through a broker.** `BROKER_URL` points at an install that holds vendor clients and performs
   the token request on your behalf. The tokens come back sealed to your install's own key, and from then
   on you talk to the vendor directly.

<Note>
  Brokering means the browser lands briefly on the broker's hostname during a connect, and there is no way
  around it: the vendor only honours a callback registered against the client. It also requires your install
  to be reachable from the public internet, because registration proves you control your own base URL by
  fetching it.
</Note>

Set `BROKER_URL=` empty to switch brokering off entirely and use only clients you registered yourself.