---
title: "Connecting to external services"
section: "Builder Guide"
canonical_url: "https://support.buildwithhq.com/builder-guide/external-api-connections.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Connecting to external services

The four ways your app talks to the outside world, and how outbound credentials are kept safe.

## In brief

- **Directions:** Two in, two out
- **Credential rule:** Encrypted at rest, never shown again
- **Related:** Appliances, Webhooks

“API” covers four different things on this platform, and support confusion usually starts with mixing them up. Here is the whole map:

| Concept | Direction | What it is |
| --- | --- | --- |
| **API clients** | Inbound → your app | Keys you issue so outside software can call *your* application's API, limited to the scopes you grant. |
| **API connections** | Your app → outbound | Credentials you store so the platform can call *remote services on your behalf* — a CRM, a payment provider, a data source. |
| **Container services** | Alongside | Appliance endpoints, plus whatever egress their manifest allows. See [Appliances and their endpoints](appliances-and-endpoints.html). |
| **Webhook actions** | Your app → outbound | Workflow steps that push signed event payloads to URLs you register. |

## Outbound: API connections

To connect a remote service, you create a connection for the app and supply its credentials — an API key, a token, whatever the service issues. From then on, workflows and features reference the connection by name; nothing else in the platform ever handles the raw credential.

How the credential is treated:

- **Encrypted before storage** with AES-256-GCM in the application tier — the database only ever holds ciphertext.
- **Never returned** — not to the browser, not through any API. After you save it, the platform can use it; no one can read it back. Lost the value? Rotate it at the remote service and save the new one.
- **Decrypted only at the moment of an outbound call**, server-side.

Tip

Create credentials at the remote service with the narrowest permissions the integration needs. If the connection is only reading contacts, the key shouldn't be able to delete them — least privilege at their end is your best protection at ours.

## Inbound: API clients

Issuing access to your app works in the opposite direction with the same discipline. You create a client with a name and a set of scopes; the secret is shown **exactly once**, at creation, and only a hash is stored. Rotation issues a fresh secret (shown once again); revocation kills the client immediately. Managing clients requires the API-keys permission on your team role.

## Outbound: webhook actions

Workflow webhook steps sign every payload, so the receiving system can verify each delivery came from your app and wasn't altered. Build receivers idempotent — deliveries retry on failure and can occasionally repeat.

## Choosing the right mechanism

- Another system needs to *push data in or query your app* → issue an **API client**.
- Your app needs to *act on a remote service* → store an **API connection** and use it from workflows.
- Another system just needs to *know when things happen* → point a **webhook** at it.
- The work needs *real compute next to your data* → install an **appliance**.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/builder-guide/external-api-connections.html).