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
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):
| key | fields |
|---|---|
account |
url, idPath, labelPath, avatarPath, headers |
api |
baseUrl, allowedHosts, auth, headers, headerFields, readOnly |
oauth |
client, authorizationUrl, tokenUrl, tokenAuth, tokenContentType, pkce, refresh, scopes, authParams, refreshParams, form, auth |
key |
label, 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:
| type | effect |
|---|---|
bearer |
prefix + token in header (defaults: Authorization, Bearer ) |
header |
prefix + token in name |
query |
the token in query parameter name |
basic |
Authorization: Basic base64(<username form value>:<token>) |
none |
no 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.
Connectors
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).
Accounts
- OAuth:
POST /api/connectors/{id}/connectwith{scopes?, values?, redirect?}returns{authorizeUrl, callbackUrl, state}. OpenauthorizeUrlin the browser and register<server>/api/connectors/oauth/callbackas the provider callback. The callback exchanges the code, stores the encrypted grant, and redirects toredirectwhen 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}/accountswith{name?, token?, tokenSecret?, values?, valueSecrets?, headers?, headerSecrets?}. A*Secretfield 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: noneneeds 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.
Calling a connected API
Pipeline step
{
"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 triggers
Plugins and external systems use the same authenticated path with an API key
that carries the workflows role:
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.
Resolution order
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.
- Introduction
- Performance
- Getting Started
- Coding Agents
- Command Line
- Infra as Code
- CI/CD Guide
- Project Boilerplate
- SDKs
- Authentication
- Databases
- Collections
- Gated Queries
- Graphs
- Rules and Access Control
- Granular Access Control
- Triggers
- Plugins
- Containers Plugin
- vski mcp
- Realtime
- Full Text Search
- Vector Embeddings
- KWH
- Workflows
- Pipelines
- Dashboard Widgets
- Connectors
- Cron
- Webhooks
- Gates
- Migrations
- Replication
- File Sync
- Backup
- Distributed Realtime
- Tutorial: ReactJS Todo
- Tutorial: Graph-Memory Agent
- Tutorial: Image Gallery
- Tutorial: Embeddings
- Tutorial: Graphs
- Recipe: Calendar Timetree
- Tutorial: Plugins
- Tutorial: MCP Server