# Connect a system

What a business system must offer before your own actions can run on it.

**In test.** The web connector has run end to end against a test system only. Don't
connect a real system yet.

Your own actions are recorded but never run until they're connected. The web
connector connects one to an HTTP API, with no code, and every call still goes
through the checkpoint.

## What the system must offer

| The system must                                                        | Why                                                |
| ---------------------------------------------------------------------- | -------------------------------------------------- |
| Offer a read endpoint for the resource                                 | Delegrity confirms each change by reading it back  |
| Return each sent value in that read                                    | A value that can't be read back can't be confirmed |
| Accept an `idempotency-key` header and not repeat a change for the key | A retried call must not act twice                  |
| Offer a status endpoint by that key                                    | A call whose answer was lost has to be resolved    |
| Accept a bearer token                                                  | The bridge sends it, and your agents never hold it |

## How it's set up

Your deployment's operator does this, not the agent:

1. Describe the system in the connector file: its address, the resource it reads
   back and the action it runs.
2. Give the bridge the system's token. Only the bridge can read it.
3. Register your action with the connector.
4. Run the no-bypass check. It confirms the system refuses calls that don't come
   through Delegrity. Without a passing check, nothing runs.

Change the system's address and the earlier check stops counting until it's run
again.

## Secret fields

A connected action can carry a secret field once the operator has set up the field
vault on both services. Without it, registering such an action is refused.

- The value is sealed to the bridge before anything is stored. The bridge opens it
  only for the call, and the sealed copy is then deleted.
- Your system receives the real value. Approvers, records and reads see only a token.
- The read-back records whether the value matched, never the value itself.
- Map each read-back field to where your system really keeps the value. A secret your
  system returns under another name can't be recognised as one.

## Not yet

- Connecting a real system: two checks are still being added first. One confirms the
  bridge and the API hold the same connector file. The other confirms your system
  accepts the bridge's real credential.