Connector catalog and OAuth2
Connect Salesforce, ServiceNow, a FHIR R4 server, Jira, Slack, Google Sheets, HubSpot, Zendesk, Stripe or any REST API from ready templates, authorize with OAuth2, and bind an action to a step — irreversible actions stay shadowed until an owner binds them live.
The generic connector binds a tool-id to an endpoint you describe field by field. The catalog does the describing for you: each template knows where the system's API lives, how it authenticates, and which actions it offers — and every action says whether it is reversible.
| Template | Auth | Reads (live) | Writes (shadowed until an owner binds them live) |
|---|---|---|---|
| FHIR R4 (Epic / Cerner style) | OAuth2 client credentials, authorization code | read a patient, search observations | send a communication, create a task |
| Salesforce | OAuth2 authorization code, client credentials | get an account, SOQL query | open a case, update an opportunity |
| ServiceNow | OAuth2 authorization code, client credentials | get / list incidents | open, update an incident |
| Jira Cloud | OAuth2 authorization code (3LO) | get an issue, JQL search | create an issue, add a comment |
| Slack | bot token, OAuth2 authorization code | look up a member by email | post a message |
| Google Sheets | OAuth2 authorization code | read a range | append a row |
| HubSpot | private-app token, OAuth2 authorization code | get, search contacts | create a contact, update a deal |
| Zendesk | OAuth2 authorization code, token | get a ticket | open, update a ticket |
| Stripe | restricted key (bearer) | get a customer, a payment intent | refund a payment, create a customer |
| Generic REST | none, bearer, header, both OAuth2 kinds | any GET path | any POST path |
A call that sends a message, moves money, or creates or changes a record is irreversible,
and the catalog says why. HubSpot's contact search is a POST that only reads; it is marked
reversible and says so. The catalog refuses to load a template that breaks these rules.
Two steps: a connection, then an action
A connection is one authorized account — a Salesforce org, a ServiceNow instance, a FHIR server. A connector binds one action on that connection to a step's tool-id. Several tool-ids share one connection, so the org is authorized once.
In the app: Settings → Connectors. Search the catalog, press Add, fill the template's fields, save. Then Bind an action on the connection.
Create a connection
curl -s -X POST "$API/connector-connections" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{
"name": "Salesforce prod",
"template_id": "salesforce",
"params": {"instance": "acme"},
"auth_kind": "oauth2_authorization_code",
"client_id": "<connected-app-consumer-key>",
"client_secret": "<connected-app-consumer-secret>"
}'Owner or admin. The response never carries a secret — only secret_set,
client_secret_set, access_token_set, refresh_token_set, the status
(ready, untested, not_authorized, error) and the last_error.
Authorize (authorization code)
Register {APP_URL}/api/connector-connections/oauth/callback as the redirect URL with the
provider (override with CONNECTOR_OAUTH_REDIRECT_URI). Then:
curl -s -X POST "$API/connector-connections/$CONNECTION_ID/authorize" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"return_to": "/settings/connectors"}'
# → {"authorize_url": "https://acme.my.salesforce.com/services/oauth2/authorize?…"}Send the browser to authorize_url (the Connect button does). The provider sends it back
to the callback, which exchanges the code and returns to the app with oauth=ok, or
oauth=error&reason=… (state, access_denied, exchange, forbidden).
- The state is single-use, expires in 10 minutes, is stored only as a SHA-256 hash, and is bound to the person who started the flow. If that person can no longer change connections when the browser comes back, the tokens are not stored.
- PKCE (S256) protects the code in transit.
return_tomust be a path on the app; anything else falls back to/settings/connectors.- Each authorization is recorded in the audit chain as
connector_connection_authorized.
Client credentials
For machine-to-machine accounts (SMART backend services, a ServiceNow or Salesforce integration user) the token is fetched from the token endpoint when first needed and cached until shortly before it expires. Test on the connection fetches one now and says whether it worked — without calling any action.
Bind an action
curl -s -X POST "$API/connector-catalog/salesforce/actions/create-case/bind" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{
"tool_id": "crm-open-case",
"connection_id": "<connection id>",
"inputs": {"Subject": "case_subject", "AccountId": "account_id"}
}'inputsmaps each action input to the run-state key it reads. An input you leave out reads the key of the same name;nulldrops an optional one. Path inputs ({account_id}) are filled the same way.- The method, path and
reversiblecome from the catalog — you cannot change them. The step inspector shows a catalog connector read-only;PUT /connectors/{tool_id}may change its mappings but refuses (409) a different method or path. live: truebinds an irreversible action live at once — owner only (403for anyone else).
Shadow until an owner binds it live
A reversible action runs live. An irreversible one is shadowed: the run records what it would have sent and sends nothing. To let its calls go out:
curl -s -X PUT "$API/connectors/crm-open-case/live" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"live": true}'Only an owner may switch it on; an admin may switch it back off ({"live": false}) — shadowing
never sends anything. Both are recorded as connector_changed with reversible_from.
Credentials
- Client secrets, tokens, access and refresh tokens are sealed with AES-256-GCM before they
reach the database, each bound to its column and company. Set
MINCTRL_SECRETS_KEY(32 bytes, base64) in production; without it the key is derived fromJWT_SECRET, and rotating that would make the stored credentials unreadable. The generic connector'sauth_tokenis sealed the same way from now on; a token saved before stays readable and is sealed on its next save. - None is ever returned by a read endpoint or written to a log or the audit chain.
- Where a call may go (SSRF guard). A base URL, token or authorize endpoint aimed at a
private, loopback, link-local or cloud-metadata address (169.254.169.254) is refused when it
is saved — a connector, a connection's URL params, a bind — and again at every call a run
makes: the host is resolved at connect time, every address must be public, and the
connection goes to the address that was checked (a name that answers differently later —
DNS rebinding — is caught). A refused call sends nothing; the step's tool result says
blockedand why. A name that does not resolve yet is accepted at save and checked at the call. On-prem deployments that call internal systems setCONNECTOR_ALLOW_PRIVATE_HOSTS=true(off by default).
When a token cannot be had
A refresh the provider refuses, an unreachable token endpoint, a secret that no longer opens:
the step's connector call fails with ok: false, auth_failed: true and the reason, and
nothing is sent. The connection turns error with that reason on the Connectors screen.
A failed credential is never an anonymous call. A shadowed connector needs no token and asks
for none.
Reference
| Endpoint | Who | What |
|---|---|---|
GET /connector-catalog?q= | member | templates, with search |
GET /connector-catalog/{template_id} | member | one template |
POST /connector-catalog/{template_id}/actions/{action_id}/bind | owner, admin | action → tool-id |
GET /connector-connections | member | connections, no secrets |
POST /connector-connections | owner, admin | create |
PATCH /connector-connections/{id} | owner, admin | change; a new client or endpoint drops stored tokens |
DELETE /connector-connections/{id} | owner, admin | refused (409) while a connector uses it |
POST /connector-connections/{id}/test | owner, admin | prove the credential, no action sent |
POST /connector-connections/{id}/authorize | owner, admin | start the authorization-code flow |
GET /connector-connections/oauth/callback | the provider's redirect | finish it |
PUT /connectors/{tool_id}/live | owner (on), admin (off) | bind a catalog action live, or shadow it |
Connect a step to your API
Bind a step's tool-id to a real HTTP endpoint with a connector, map inputs, and control shadowing of irreversible tools.
Configure gates and autonomy
How the resolver routes a step by risk tier — low auto-clears, medium goes to a judge panel, irreversible always parks for a human — and how reversibility and blast radius decide the tier.