> For the complete documentation index, see [llms.txt](https://docs.emseapea.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.emseapea.ai/admin-guide/connecting-a-system.md).

# Connecting a system

Adding a system to your allow-list lets builders *request* it. Configuring its connection is what lets their approved apps actually *reach* it.

Two steps, and the second one happens in your own vendor console — Emseapea never asks for, and never stores, a client secret. Secrets live on your gateway.

Both steps assume the vendor-side machine account already exists. [Systems your apps can reach](/setting-up-your-accounts/systems-apps-can-reach.md) is what to read first: what to create with each vendor, why it must never be a personal login, and how far each one has actually been proven.

## Step 1 — add the system

**Settings → Data Systems → Add a system**

You only type one thing: **what your team calls it** — e.g. "Salesforce CRM." The **short name** builders will actually request (lowercase letters, numbers and dashes, e.g. `salesforce-crm`) is filled in automatically from that as you type, shown so you can see it, and free to edit if you'd like something different.

That is enough for it to appear in the request form. Requests for anything *not* on this list are still recorded, but they are routed to an admin instead of a regular approver — never silently granted, never silently dropped.

## Step 2 — configure the connection

**Settings → the system → Set up connection**

| Field                     | What it is                                                 |
| ------------------------- | ---------------------------------------------------------- |
| Web address of the system | The API root, e.g. `https://yourorg.crm11.dynamics.com`    |
| How Emseapea signs in     | "Client credentials (app-to-app)" for the vendors below    |
| Application (client) ID   | From the app registration you create in the vendor console |
| Sign-in (token) address   | The vendor's OAuth token endpoint                          |
| Scope                     | Only if the vendor requires one                            |
| Client secret             | **Disabled here by design** — it is set on your gateway    |

**Test connection** tells you exactly where you stand: what is missing, whether the vendor accepted the sign-in, or whether the system could not be reached.

***

## Microsoft (Dataverse / Dynamics)

1. **Create the app registration** — [entra.microsoft.com](https://entra.microsoft.com) → Applications → App registrations → **New registration**. Name it `emseapea-gateway`, choose **single tenant**, leave the redirect URI blank. Copy the **Application (client) ID** and the **Directory (tenant) ID**.
2. **Create a client secret** — the app's **Certificates & secrets** → **New client secret** → copy the **Value** immediately (it is shown once). This goes to your gateway, not into Emseapea.
3. **Let the app into your environment** — [admin.powerplatform.microsoft.com](https://admin.powerplatform.microsoft.com/environments) → your environment → **Settings → Users + permissions → Application users** → **New app user** → add `emseapea-gateway` → give it a security role (**System Customizer** is a reasonable starting point). *Without this step the app can get a token but Dataverse will refuse it.*
4. **Fill in Emseapea**:
   * Web address: `https://yourorg.crm11.dynamics.com`
   * Sign-in address: `https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token`
   * Scope: `https://yourorg.crm11.dynamics.com/.default`

## Salesforce

1. **Create an External Client App** — Setup → **App Manager** → **New External Client App**. Name it `emseapea_gateway` (underscores; dashes are not accepted). Enable **OAuth**, set the callback URL to `https://login.salesforce.com/services/oauth2/callback` (a required placeholder), and add the scope **Manage user data via APIs (api)**.
2. **Enable client credentials** — the app's **Policies** tab → **Edit** → tick **Enable Client Credentials Flow** and set **Run As** to an integration user. *This is a user picker: type the person's **name**, not their username, and select them from the dropdown.* Everything the gateway does will be attributed to that user in your audit trail.
3. **Get the credentials** — **Settings → OAuth Settings → Consumer Key and Secret** (Salesforce may email you a verification code). The **Consumer Key** is the client ID; the **Consumer Secret** goes to your gateway.
4. **Fill in Emseapea**:
   * Web address: `https://yourdomain.my.salesforce.com`
   * Sign-in address: `https://yourdomain.my.salesforce.com/services/oauth2/token`
   * Scope: leave blank

> Changes to a Salesforce connected app can take **2–10 minutes** to propagate. If Test connection fails immediately after saving there, wait and try again.

## Where the secret actually lives

Your gateway holds it as `UPSTREAM_SECRET_<SHORT_NAME>` — for example `UPSTREAM_SECRET_DATAVERSE`. It is never written into Emseapea's database: you type it once on Settings → Gateway and it goes straight onto the gateway as a secret. The apps your builders create never see it either — they carry only a short-lived Emseapea access key, and the gateway exchanges it for real vendor access on the way through.

**One correction worth making here.** That gateway is meant to run in *your* cloud, and today it does not — it runs in a Cloudflare account Emseapea controls. The secret is still a gateway secret rather than a stored row, but it does not yet stay inside your tenancy. See [Cloudflare, for the gateway we include](/setting-up-your-accounts/cloudflare-for-the-gateway.md).

## Next

Adding a system here only lets builders request it. Once they do, most requests will ask for it as **wider access, set up by IT** — see [Curating prepared accounts](/admin-guide/prepared-accounts.md) for setting those up, and [The two kinds of access](/builder-guide/kinds-of-access.md) for the reasoning a builder sees when choosing between the two.