Connectors — Croft

Most people never touch this

The easiest way to add a connector is to ask your assistant — "connect our Stripe account" — and it reads the tool's API documentation and fills in the details for you. This page is for developers who want to set one up by hand.

The fields on the manual form

Field	What it is
Name	A short label, lowercase, e.g. `stripe`. Apps refer to the connector by this name.
Base URL	The API’s address, always `https://…`, e.g. `https://api.stripe.com`. Every operation’s path is added onto this.
How it authenticates	How the tool expects its key (see Auth styles).
Header / parameter name	Only for the “custom header” or “URL query parameter” styles — the name of the header or query parameter the key goes in (e.g. `X-Api-Key`).
Operations	The list of actions apps can perform, as JSON (see below).
API key	The secret from the tool. Held only by Croft — never shown to apps. You can add it now or later; the connector stays off until it has a key and is switched on.

Auth styles

Style	What Croft sends	Needs a name?
Bearer token (most common)	`Authorization: Bearer <key>`	no
Custom header	`<name>: <key>`	yes — the header name
URL query parameter	`…?<name>=<key>`	yes — the parameter name
Username & password	HTTP Basic auth	no — enter a username and password instead of a key

The Operations JSON

Operations is a JSON object. Each key is an operation name (lowercase letters, numbers, and underscores) that apps will call; each value describes the request:

{
  "list_orders": { "method": "GET",  "path": "/v2/orders",      "params": ["status", "limit"] },
  "get_order":   { "method": "GET",  "path": "/v2/orders/{id}", "params": [] },
  "create_note": { "method": "POST", "path": "/v2/notes",       "params": ["order_id", "text"] }
}

Each operation has three properties:

method — the HTTP method: GET, POST, PUT, PATCH, or DELETE.
path — the path added onto the Base URL. Must start with /. It may contain placeholders in curly braces, e.g. {id}, which get filled in from the call’s parameters.
params — the parameter names the operation accepts, besides any placeholders in the path. Optional; omit it or use [] if there are none.

How parameters are used

When an app calls an operation it passes a set of params. Croft places them depending on the method:

Path placeholders ({id}) are always filled from the matching param.
For GET and DELETE, the remaining params are added to the URL query string (?status=open&limit=20).
For POST, PUT, and PATCH, the remaining params are sent as a JSON request body ({ "order_id": "123", "text": "…" }).

So for get_order above, calling it with { "id": "or_123" } requests GET https://api.vendor.com/v2/orders/or_123.

What’s rejected when you save

The Base URL must be https://, and can’t point at an internal or private address.
Each path must start with /, and can’t contain .., //, or a scheme/host — a path can only ever address the connector’s own Base URL host.
Operation and parameter names must be simple: letters, numbers, and underscores.
Up to 50 operations per connector.

How an app calls a connector

For app developers — when your assistant builds an app that uses a connector, it writes this for you.

Apps never hold the key. They call the connector through Croft’s internal broker:

POST http://croft-data:8080/call/<connector>/<operation>
Authorization: Bearer <the app's own CROFT_DATA_TOKEN, provided by Croft>
Content-Type: application/json

{ "params": { "status": "open", "limit": 20 } }

The response is { "status": <the API's HTTP status>, "body": <the API's JSON> }. Croft attaches the real key on the way out.

Handle “not ready” gracefully. If the connector hasn’t had its key added yet, or the app hasn’t been given access, the broker replies with a clear error (no_connector or no_grant). Show the user a calm message like “This integration isn’t switched on yet” rather than an error.

Custom headers and a raw body

The broker request can carry the call directly — method, path, and params — plus two optional fields for APIs with particular needs:

headers — extra request headers passed through to the API, for example a specific Content-Type.
body — a raw request body, sent verbatim in place of params (useful when the API wants a non-object body, like a JSON array).

For example, an Azure DevOps work-item update needs the application/json-patch+json content type and a JSON array body:

{
  "method": "PATCH",
  "path": "/{project}/_apis/wit/workitems/{id}?api-version=7.1",
  "params": { "project": "Acme", "id": "42" },
  "headers": { "Content-Type": "application/json-patch+json" },
  "body": [ { "op": "add", "path": "/fields/System.Title", "value": "New title" } ]
}

The connector’s credential is always attached last and can’t be overridden by your headers — so a custom header can never replace or leak the key.

A full worked example: GitHub

Connector:

Name: github
Base URL: https://api.github.com
Auth: Bearer token, with the key being a GitHub personal access token
Operations:

{
  "get_repo":    { "method": "GET", "path": "/repos/{owner}/{repo}",        "params": [] },
  "list_issues": { "method": "GET", "path": "/repos/{owner}/{repo}/issues", "params": ["state", "per_page"] }
}

An app calls POST /call/github/list_issues with { "params": { "owner": "rails", "repo": "rails", "state": "open", "per_page": 5 } } → Croft requests GET https://api.github.com/repos/rails/rails/issues?state=open&per_page=5 with the token attached, and returns the JSON.