Instance Connections

An instance connection links your Operator account to a specific ERP.net instance (identified by its base URL, e.g. https://demodb.my.erp.net). Every chat, app, automation and search runs against a single active connection at a time.

You can have as many connections as you need — one per instance you work with, or even multiple connections to the same instance (for example, one as an Internal User and one as a Client).

Connection types

• Internal User — you log in interactively with your own ERP.net account through the standard sign-in screen. Use this for instances where you have your own user (employees, partners, internal users).
• Client — the instance is contacted via stored client credentials configured in the instance. Use this when you don't have a personal user but the instance owner has granted you a client identity (typically external customers).

Internal connections support OAuth refresh, so you stay signed in across sessions until the refresh token expires. Client connections re-authenticate transparently from the stored credentials.

Where you manage connections

There are two places in the UI:

Instance selector (top bar)

The dropdown in the top bar shows all your connections, with the active one ticked. From here you can:

• Switch the active connection — pick any connection in the list. The whole app reloads its context (entity schemas, agents, tools, capabilities) for the new instance.
• Add a new connection — opens the same dialog as on the My Connections page.
• Buy AI Credits — only shown when the active instance is one you administer. Routes to /billing-credits.
• See connection status — a coloured dot on each entry indicates Active / Expired / Disconnected.

My Connections page

Open it from the user menu or directly at /my-instance-connections. This is the full management surface — name, type, home flag, AI credit budget, status, enterprise/client context, plus connect / reconnect / disconnect actions. The rest of this page describes what you can do there.

Adding a connection

Click Add New in the top right. In the dialog:

1. Instance URL — type the instance subdomain (e.g. demodb); Operator wraps it as https://<name>.my.erp.net.
2. Display Name — how the connection appears in the selector. Auto-generated from the instance name; override freely.
3. Connect as — choose Internal User (you sign in with your own ERP.net account) or Client (stored client credentials). See Connection types.
4. Set as my home connection — only offered for the very first internal connection (when you don't have a home yet).

Click Add Instance. For Internal connections, the next time you select the connection you'll be taken through the ERP.net sign-in flow; the resulting tokens are stored against the connection.

Editing a connection

Use the row's ⋯ menu → Edit. You can rename it and adjust connection-type-specific fields. For an existing non-home internal connection you'll also see the AI credit budget picker — see AI credit budget per connection.

The home connection

Exactly one of your connections is marked as your home connection (shown with a 🏠 badge). The home connection is your default billing target for AI usage when you haven't overridden it on a per-connection basis.

The first internal connection you add is automatically set as home. To change it later, open the row's ⋯ menu and pick Set as home — the previous home loses the badge.

AI credit budget per connection

Each connection pays for its AI usage from one of two budgets:

• Home connection (default) — credits come from your home connection's instance pool.
• This instance — credits come from a per-instance budget that the instance admin allocated specifically to you on this instance.

You change this in My Connections → Edit Instance, under AI credit budget. The dialog shows the current balance for both options.

When "This instance" is selectable — only once an instance admin on that instance has topped you up there. Until then the option is disabled with the hint "ask the instance admin to top you up". See Managing User Budgets for the admin-side view.

No silent fallback — if you choose This instance and that budget runs out, AI calls on that connection will fail with an explicit error. They will not silently fall back to your home pool. This is intentional — it lets the party that funds the budget control spend on that connection.

When this matters — the classic scenario is an external consultant connecting to a customer's instance. By default the consultant's AI usage on that connection bills their own home pool. Once the customer's instance admin allocates AI credits to the consultant on that instance, the consultant can switch the connection to This instance and from then on usage is billed to the customer-funded budget. If that budget is exhausted, the consultant gets an error rather than silently consuming their own credits.

See also: Buying AI Credits and Managing User Budgets.

Connecting, reconnecting, disconnecting

The ⋯ menu adapts to the current status:

• Connect — appears when the connection has no valid access token. Loads tokens from storage if possible, otherwise opens the ERP.net sign-in flow.
• Reconnect — for an active connection, forces a fresh sign-in (useful after permission changes on the instance).
• Disconnect — clears the in-memory tokens for the active connection. The connection row itself stays; tokens stay encrypted in storage and can be reused via Connect.

Setting the enterprise / client context

Once a connection is active, the ⋯ menu shows either Set Enterprise Context (internal connections) or Set Client Context (client connections). This pins which company / location / customer is implied in subsequent AI requests, so you don't have to spell it out every time.

Removing a connection

⋯ → Delete removes the connection record and any stored tokens. The instance itself isn't affected — you can re-add it later. You can't delete the only remaining connection that's currently set as home unless another one becomes home first.

Status indicators

Each connection has one of three statuses, shown in both the top-bar dropdown and the My Connections table:

• Active (green) — there's a valid access token; the instance is reachable.
• Expired (gray) — the access token expired but a refresh token is still on file (or the connection is a Client connection that can re-authenticate). One click on Connect or Reconnect restores it.
• Disconnected (muted) — no usable tokens. You'll be sent through the sign-in flow next time you select the connection.

Hovering the badge shows exact expiry timestamps for both the access and refresh tokens.

Troubleshooting

If a connection refuses to come up:

• Check that Operator is installed in the instance (you'll see a banner if it isn't).
• For Client connections, verify the client credentials configured on the instance side haven't been rotated.
• Try Reconnect to force a fresh sign-in.