# Private connections

Let an agent check an internal order without giving your order service a public endpoint. Set up access, approve requests, and test the connection from your dashboard.

[Open private connections](https://bezalel.sh/dashboard/connectors/private) · [Contact Bezalel for setup](https://bezalel.sh/contact)

## How it works

An agent asks Bezalel for an order. Bezalel checks access and approval, then calls an authenticated HTTPS worker. The worker reaches your internal order service through a private gateway and returns selected facts.

Each connection supports one fixed order lookup. Agents cannot choose a URL, send SQL, or run arbitrary commands through it. Private databases and customer-hosted MCP servers are not supported by this connector.

## Prepare your connection

Gateway and worker provisioning currently needs your network operator and the Bezalel team. Contact us to arrange setup before using Add connection. The dashboard registers an existing worker; it does not create the tunnel.

Your operator must give the worker a private route to one fixed IPv4 address and port for the order service. The service must support GET /orders/:orderId. Restrict routing and firewall access to that service, use HTTPS for the authenticated worker endpoint, and confirm the gateway can reach the service.

Ask your operator for the connection ID, worker HTTPS origin, and worker token. The connection ID must match the provisioned worker. Use an origin such as https://orders.example.com with a hostname, no custom port, and no trailing slash or path. Keep the token in a password manager and enter it only in the dashboard, not in agent prompts.

You also need an active Bezalel agent with the connectors scope and a known order ID for testing. Your operator keeps the internal service credential on the worker; it does not belong in the dashboard form.

## Add the connection

1. Open Connectors → Private connections in your dashboard and click Add connection. Continue once your operator has prepared the worker and gateway.
2. Enter a display name, the provisioned connection ID, the worker HTTPS origin, and the worker token.
3. Choose which agents may use the connection. Only active agents with the connectors scope are eligible. Keep owner approval on if you want to review each order request.
4. Set a daily request limit from 1 to 1,000 and save. New connections start paused. The form clears the token on submission; if saving fails, enter it again.
5. Resume when the gateway is ready. Enabled means requests are allowed; it does not confirm that the network is connected. Use Test connection to verify a read.

## Test an order

A dashboard test performs a real order read as the selected agent. It uses the same permissions, approvals, and request limit as an agent call.

1. Click Test connection, choose an allowed agent, and enter a known order ID.
2. If approval is required, review the agent and order, then choose Approve and run test. This grants one request and retries the read.
3. Check the returned order facts and the test outcome in Activity. Ask your operator to test recovery after a tunnel interruption before relying on the connection.

## Use it from your agent

The agent discovers its allowed connections with connectors__list_private_connections. It then calls connectors__investigate_order with the connection ID and order ID. Replace these example IDs with your own.

If the tool returns approval_required, review the request in the dashboard Approvals tab. After approval, the agent retries with the same connectionId and orderId plus the returned approvalId. The worker token is never an agent tool argument.

### connectors__investigate_order

```json
{
  "connectionId": "orders",
  "orderId": "ORD-1003"
}
```

## Approvals and limits

Approvals expire after ten minutes and cover one agent, one order, and one connection version. They cannot be reused. Changing settings invalidates earlier approvals. If the worker fails after consuming an approval, a retry needs a new decision.

The daily limit is shared across the connection and resets at midnight UTC. Worker attempts count, including tests and failed reads. Requesting approval does not count. A request rejected before admission does not consume its approval. Settings edits keep the count for the current day.

Settings lets you change the name, allowed agents, approval policy, and limit without re-entering the worker token. Pause stops new requests; a request already admitted may finish. Credential rotation requires your operator to update the worker and its matching saved credential together.

## Troubleshooting

No agent to select: create or enable an agent with the connectors scope, then allow it in the connection settings.

Test unavailable: resume the connection and select an allowed agent. If access was changed or revoked, review its current scopes and connection settings.

Approval expired or settings changed: request a fresh approval. A consumed approval cannot be used for another attempt.

Daily limit reached: wait until midnight UTC or have the owner raise the limit. Editing other settings does not reset usage.

Worker or service error: ask your operator to check the HTTPS endpoint, matching worker credential, tunnel, route, firewall, and internal service. Enabled alone is not a health check. Retry Test connection after the operator restores access.

Order not found: check the order ID with your internal system. An unavailable dashboard section means its data could not be loaded; it does not mean there are no connections or requests.

## What data is shared

Results contain the order ID, order and payment status, item count, total, currency, shipment status, and a fixed exception code. The worker removes names, email addresses, payment credentials, free text, and links. Bezalel validates the result again.

Returned facts can reach the model provider used by your agent. Private networking keeps the internal service off the public internet; it does not keep returned facts inside your network.

Worker credentials are encrypted in storage and are not returned by dashboard reads. Activity shows the latest 100 attempts without order results or credentials. The approval queue stores the requested order ID for owner review. Activity and approval records currently have no automatic retention period.

## Disconnect and clean up

Pause the connection to stop new requests temporarily, or choose Remove and confirm to stop Bezalel access. Removing a connection retains its activity history.

Removal does not delete the worker, tunnel, or customer gateway. Ask your operator to remove those resources, revoke the internal service credential, and delete protected configuration files when they are no longer needed.

[All developer docs](https://bezalel.sh/docs)