Skip to content

Connectors

Connectors let pipelines, plugins, and triggers call third-party APIs without holding provider tokens. A definition describes a provider; a connector is one configured instance of it; an account is an authorized credential (OAuth grant, API key, basic password, custom headers, or no credential). Definitions and configs are declared as YAML, stored in system collections, and all credentials are encrypted at rest.

Definitions are data and are not built into the server. Declare them in your IaC directory under connectorDefinitions; vski apply stores them in the _connector_definitions system collection, and the dashboard offers them when adding a connector. There are no hidden built-ins to override.

vski pull exports every live definition to connector-definitions.yaml and every configured connector to connectors.yaml.

version: 1
connectorDefinitions:
internal-api:
name: Internal API
description: Internal project API
docs: https://docs.example.com/api
account:
url: https://api.example.com/me
idPath: id
labelPath: email
api:
baseUrl: https://api.example.com
allowedHosts: [api.example.com]
auth: {type: bearer, header: Authorization, prefix: "Bearer "}
headers: {Accept: application/json}
key:
label: API key
auth: {type: bearer, header: Authorization, prefix: "Bearer "}
oauth:
client: {registration: static}
authorizationUrl: https://auth.example.com/authorize
tokenUrl: https://auth.example.com/token
tokenAuth: client_secret_post
tokenContentType: form
refresh: true
scopes:
default: [read, offline_access]
optional:
- {value: write, label: Write data, danger: true}

The definition schema (top-level name, description, icon, docs, and metadata are optional):

keyfields
accounturl, idPath, labelPath, avatarPath, headers
apibaseUrl, allowedHosts, auth, headers, headerFields, readOnly
oauthclient, authorizationUrl, tokenUrl, tokenAuth, tokenContentType, pkce, refresh, scopes, authParams, refreshParams, form, auth
keylabel, form, auth

account.url is a profile endpoint. For OAuth accounts the platform fetches it after the grant completes and stores the values at idPath, labelPath, and avatarPath as the account identity. Key and custom-header accounts use the name supplied when they are connected.

api.readOnly: true rejects every method except GET and HEAD. api.headerFields declares the header values a custom-header account supplies. api.baseUrl and api.allowedHosts may contain {field} placeholders, resolved from the values entered when the account is connected.

An auth scheme says how a credential is attached:

typeeffect
bearerprefix + token in header (defaults: Authorization, Bearer )
headerprefix + token in name
querythe token in query parameter name
basicAuthorization: Basic base64(<username form value>:<token>)
noneno credential

form declares extra values collected when an account is connected, such as an email used by basic auth or a value substituted into a {field} placeholder.

Definition ids match [a-z0-9][a-z0-9-]{0,63}. version must be 1, name is required, and api.baseUrl is required when api is present. OAuth definitions require authorizationUrl and tokenUrl. When set, client.registration must be static, tokenAuth must be none, client_secret_post, or client_secret_basic, and tokenContentType must be form or json.

A connector config names a definition and optionally overrides its endpoints, auth scheme, headers, form, scopes, and token settings. Omitted fields keep the definition defaults.

connectors:
internal:
definition: internal-api
name: Internal API
authType: oauth
clientId: your-client-id
clientSecret: {fromSecret: INTERNAL_CLIENT_SECRET}

authType is oauth, key, headers, or none. When omitted, the config uses OAuth if the definition declares it, then a key, then custom headers, then no credential. The full IaC field list is in IaC.

The OAuth client secret references the encrypted VSKI secrets store, so it is never written to YAML or returned by the connector API. {fromEnv: NAME} is also accepted for CI. Accounts are connected interactively and never live in YAML; their API keys and custom headers can reference stored secrets too.

GET /api/connectors/definitions lists the catalog. GET /api/connectors lists configured connectors. Credential values are never returned; a connector that references the secrets store exposes only the secret name (clientSecretSecret).

  • OAuth: POST /api/connectors/{id}/connect with {scopes?, values?, redirect?} returns {authorizeUrl, callbackUrl, state}. Open authorizeUrl in the browser and register <server>/api/connectors/oauth/callback as the provider callback. The callback exchanges the code, stores the encrypted grant, and redirects to redirect when supplied (a dashboard-relative path), otherwise to /connectors?connected=.... The state is single-use and expires after 10 minutes.
  • API key, basic password, custom headers: POST /api/connectors/{id}/accounts with {name?, token?, tokenSecret?, values?, valueSecrets?, headers?, headerSecrets?}. A *Secret field names an entry in the encrypted secrets store and is resolved at request time, so rotating the secret updates every connector that references it.
  • authType: none needs no account.

List accounts with GET /api/connectors/{id}/accounts; remove one with DELETE /api/connectors/{id}/accounts/{accountId}. Account responses include the name, status, identity, and expiry, never the credential.

OAuth access tokens refresh automatically when an expiry is known, the token is close to it, the flow has a refresh token, and oauth.refresh: true. An account without an expiry, a refresh token, or refresh: true is not refreshed automatically; reconnect it when the provider rejects the token.

{
"id": "projects",
"type": "connector",
"connector": "internal",
"account": "{{input.account}}",
"method": "GET",
"path": "/v1/projects?limit=50",
"dependsOn": ["prepare"]
}

Fields: connector (required), account (id or name; default is the first active account), method (default GET), path (appended to the connector’s base URL) or url (absolute, must pass the allowed-host check), headers, body, timeout (seconds, default 30, max 120), plus the usual dependsOn, condition, retries, and onError.

account is templated like the other fields, so "{{input.account}}" lets one pipeline run against any connected account. Output is {status, headers, body}, with a JSON body decoded for {{steps.<id>.output.body.<field>}}. Non-2xx responses fail the step so retries and onError work as usual.

Plugins and external systems use the same authenticated path with an API key that carries the workflows role:

Terminal window
curl -X POST "$VSKI/api/connectors/internal/request" \
-H "X-API-Key: $WORKFLOWS_KEY" -H "Content-Type: application/json" \
-d '{"method":"GET","path":"/v1/projects?limit=1"}'

Body: {method?, path?, url?, headers?, body?, account?, timeoutMs?}. Response: {status, headers, body}. The proxy answers 200 and reports the provider’s code in status; transport, configuration, and host errors use 4xx or 5xx. Pipeline triggers already run pipelines, so their connector steps use the same engine; no provider token is exposed to the trigger caller.

Management endpoints require an admin session unless noted otherwise; the request endpoint requires the workflows role, which admins also have.

A request uses the definition’s API auth, overridden per account type: OAuth uses oauth.auth then api.auth then Bearer; API key uses key.auth then api.auth then Bearer. Custom headers attach the value of every declared api.headerFields entry.

Static api.headers are applied first; caller headers may replace them, but never the computed credential. Only hosts in api.allowedHosts (plus the resolved base URL host) are reachable, matched exactly with no wildcards. A disabled connector rejects account and request calls.