Overview

A Connection is a named, stored set of credentials and configuration for an external service — an LLM provider API key, a PostgreSQL host and password, a Pinecone account, an MCP server URL. You create a Connection once per project, then reference it everywhere: workflow nodes, Knowledge Bases, the AI gateway, and evaluation metrics all resolve credentials through Connections instead of holding raw secrets.

How Connections work

Every Connection has four parts:

• Name — a label you choose, unique enough to identify it in pickers ("openai-prod", "analytics-postgres").
• Type — the service it connects to, such as dynamiq.connections.OpenAI or dynamiq.connections.PostgreSQL. The type determines which config fields the Connection accepts. See the full catalog in Create a Connection.
• Config — the type-specific fields: an api_key for most LLM providers, host/port/database/user/password for SQL databases, OAuth scopes for cloud storage providers.
• Status — one of active, incomplete, or expired. Most Connections are active immediately after creation; OAuth Connections stay incomplete until you authorize them with the provider, and become expired if their tokens can no longer be refreshed.

Project scoping

Connections belong to a project. You create them inside a project, and the resources in that project — workflows, Knowledge Bases, deployed Apps — pick from that project's Connections. When you list Connections through the API you filter by project_id.

Where Connections are used

Connections vs. Connectors

These are different things:

• A Connection (this section) is project-scoped stored credentials/config used by workflows, Knowledge Bases, and the gateway.
• A Connector is an OAuth app integration that individual users link in Chat — for example connecting your own Google Drive so the Chat agent can read your files. Connectors are per-user; Connections are shared across the project.

Security model

• Secrets stay server-side. Connection secrets are stored encrypted and are never embedded in workflow definitions. A workflow JSON references a Connection only by its ID; the execution engine fetches the credentials at runtime.
• The API redacts sensitive data. When you read a Connection back, OAuth tokens and state are stripped from the response, and system-managed Connections return no config at all.
• Credentials access is explicit. Raw credentials are only returned by the dedicated POST /v1/connections/{connection_id}/credentials endpoint, which requires authenticated access to the project.

API quick reference

All endpoints live on the management API at https://api.getdynamiq.ai and require a Authorization: Bearer token.

List the Connections in a project:

curl "https://api.getdynamiq.ai/v1/connections?project_id=$DYNAMIQ_PROJECT_ID" \
  -H "Authorization: Bearer $DYNAMIQ_ACCESS_KEY"

import os

import requests

response = requests.get(
    "https://api.getdynamiq.ai/v1/connections",
    headers={"Authorization": f"Bearer {os.environ['DYNAMIQ_ACCESS_KEY']}"},
    params={"project_id": os.environ["DYNAMIQ_PROJECT_ID"]},
)
response.raise_for_status()

for connection in response.json()["data"]:
    print(connection["name"], connection["type"], connection["status"])

const params = new URLSearchParams({
  project_id: process.env.DYNAMIQ_PROJECT_ID!,
});

const response = await fetch(
  `https://api.getdynamiq.ai/v1/connections?${params}`,
  {
    headers: {
      Authorization: `Bearer ${process.env.DYNAMIQ_ACCESS_KEY}`,
    },
  },
);

const { data } = await response.json();
for (const connection of data) {
  console.log(connection.name, connection.type, connection.status);
}

Next steps