Connections API
Store provider credentials, create and test connections, discover capabilities, rotate credentials and run entity syncs.
Updated 07/10/2026
On this page
All paths start with /api/console/connect and need a session token. The required workspace permission is shown for each endpoint.
Credentials
| Method | Path | Permission | Description |
|---|---|---|---|
GET | /credential-setup | connect.connection.create | {available, providers: {<connectorKey>: [{key, label, description, optional}]}}: the credential fields each connector needs |
POST | /credential-references | connect.connection.create | Stores credentials in Key Vault and returns {secretReference, stored: true} |
POST /api/console/connect/credential-references
{
"connectorKey": "hubspot",
"credentials": { "accessToken": "<private app token>" }
}Only the fields declared for the connector are accepted. Each value must be non-empty, at most 4,096 characters, with no line breaks. Returns 503 if the workspace has no managed vault.
Create a connection
POST /connections (connect.connection.create)
| Field | Type | Notes |
|---|---|---|
connectorKey | string | A connector with an operational runtime, for example xero or jira |
projectId | string | Must belong to the workspace |
name | string | 3–100 characters, unique in the workspace |
environment | sandbox or production | Default sandbox |
slug | string | Optional |
configuration | object | Provider settings (below) |
configuration accepts the connector's declared settings plus:
secretReference: the Key Vault secret URI, which must sit in the managed vault under connect-<workspaceId>-…;
baseUrl: only where the connector allows a customer-specific host;
allowedWriteOperations: an array of write operation keys this connection may run;
authentication, accountReference, organisationReference.
Unknown settings and secret-like keys (password, apiKey, token, clientSecret, authorization, credential) return 400. A base URL outside the provider's documented origin also returns 400.
POST /api/console/connect/connections
{
"connectorKey": "jira",
"projectId": "proj_123",
"name": "Jira operations",
"environment": "sandbox",
"configuration": {
"site": "acme",
"allowedWriteOperations": ["issues.create"],
"secretReference": "https://<vault>.vault.azure.net/secrets/connect-<workspace>-jira"
}
}The response is the connection with status: "draft", healthStatus: "unknown" and the derived providerBaseUrl. The secret reference is never returned in configuration.
Manage connections
| Method | Path | Permission | Description |
|---|---|---|---|
GET | /connections | connect.connection.read | All connections, newest first, with connector, secret status and the latest health check |
GET | /connections/:id | connect.connection.read | One connection with its last 20 health checks |
PATCH | /connections/:id | connect.connection.update | {name?, configuration?}. Returns the connection to draft. |
POST | /connections/:id/test | connect.connection.test | Runs the health check. Success: {status: "healthy", latencyMs, detail}, and the connection becomes active. |
POST | /connections/:id/rotate-credentials | connect.connection.rotate_secret | {secretReference}. Returns the connection to draft. |
POST | /connections/:id/disable | connect.connection.update | Disables the connection |
GET | /connections/:id/health | connect.connection.read | Health check history |
GET | /connections/:id/capabilities | connect.connection.read | Capability manifest; add ?refresh=true to rediscover |
GET | /connections/:id/account-context | connect.connection.read | Cached capability manifest |
Capability manifest
Each operation in the manifest includes:
its key, display name, mode (read or write) and entity;
input and output schemas, required permissions and pagination;
idempotency, approvalRequired and risk level;
availability.state: available or permission_required.
If discovery is not possible, the reason is one of CONNECTION_NOT_ACTIVE, CAPABILITY_DISCOVERY_EMPTY, CAPABILITY_DISCOVERY_FAILED or ADAPTER_UNAVAILABLE. Successful discoveries are cached for 60 seconds, failures for 15 seconds.
Entity sync (commerce connectors)
| Method | Path | Permission | Description |
|---|---|---|---|
POST | /connections/:id/sync | connect.flow.execute | Starts a sync run |
GET | /connections/:id/sync-runs | connect.connection.read | The 50 most recent runs |
GET | /connections/:id/sync-records?entity= | connect.connection.read | Up to 1,000 synced records |
The sync body:
environment: must match the connection's environment;
entities[]: any of products, prices, customers, orders, deliveries and inventory (default all);
idempotencyKey and correlationId: required;
pageSize: 1–100, default 100.
Replaying a key returns the existing run with replayed: true.
Xero authorisation
GET /xero/connections/:id/oauth/start (connect.connection.update) returns {provider, authorizeUrl, expiresInSeconds: 600}. Send the user to authorizeUrl; Xero redirects back to Nexra, which completes the connection.