Minctrl Docs
Guides

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.

TemplateAuthReads (live)Writes (shadowed until an owner binds them live)
FHIR R4 (Epic / Cerner style)OAuth2 client credentials, authorization coderead a patient, search observationssend a communication, create a task
SalesforceOAuth2 authorization code, client credentialsget an account, SOQL queryopen a case, update an opportunity
ServiceNowOAuth2 authorization code, client credentialsget / list incidentsopen, update an incident
Jira CloudOAuth2 authorization code (3LO)get an issue, JQL searchcreate an issue, add a comment
Slackbot token, OAuth2 authorization codelook up a member by emailpost a message
Google SheetsOAuth2 authorization coderead a rangeappend a row
HubSpotprivate-app token, OAuth2 authorization codeget, search contactscreate a contact, update a deal
ZendeskOAuth2 authorization code, tokenget a ticketopen, update a ticket
Striperestricted key (bearer)get a customer, a payment intentrefund a payment, create a customer
Generic RESTnone, bearer, header, both OAuth2 kindsany GET pathany 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_to must 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"}
  }'
  • inputs maps each action input to the run-state key it reads. An input you leave out reads the key of the same name; null drops an optional one. Path inputs ({account_id}) are filled the same way.
  • The method, path and reversible come 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: true binds an irreversible action live at once — owner only (403 for 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 from JWT_SECRET, and rotating that would make the stored credentials unreadable. The generic connector's auth_token is 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 blocked and why. A name that does not resolve yet is accepted at save and checked at the call. On-prem deployments that call internal systems set CONNECTOR_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

EndpointWhoWhat
GET /connector-catalog?q=membertemplates, with search
GET /connector-catalog/{template_id}memberone template
POST /connector-catalog/{template_id}/actions/{action_id}/bindowner, adminaction → tool-id
GET /connector-connectionsmemberconnections, no secrets
POST /connector-connectionsowner, admincreate
PATCH /connector-connections/{id}owner, adminchange; a new client or endpoint drops stored tokens
DELETE /connector-connections/{id}owner, adminrefused (409) while a connector uses it
POST /connector-connections/{id}/testowner, adminprove the credential, no action sent
POST /connector-connections/{id}/authorizeowner, adminstart the authorization-code flow
GET /connector-connections/oauth/callbackthe provider's redirectfinish it
PUT /connectors/{tool_id}/liveowner (on), admin (off)bind a catalog action live, or shadow it

On this page