Connections & Secrets

Technical reference. This page is for integrations, advanced configuration, or platform operations. For portal tasks, start with the user guide.

Orqestra manages integration configuration separately from credentials. Connection instances store non-secret configuration and bind named secret slots to workspace- and environment-scoped secrets. Runtime execution resolves secret values only when a flow needs them.

HashiCorp Vault is supported for local and deployed environments. Cloud deployments can also use their provider-native secret managers: Azure Key Vault, AWS Secrets Manager, or Google Secret Manager. Choose the backend that matches your operating model, identity controls, rotation process, audit requirements, and network boundaries.

Concepts

Secret values are not stored inside governed assets. Flow definitions can refer to connection slots, and the runtime resolves the underlying value during execution.

ORQESTRA_PLUGIN_INLINE_CREDENTIALS controls the official-plugin fallback policy (allow or deny). It defaults to allow for compatibility; AKS configuration sets deny. Caller inputs cannot change this deployment setting. In deny mode, use a governed connection or supported delegation instead of supplying a credential directly to a plugin.

A connector_definition (as installed by an official or community plugin package — see Plugins & Connectors) is catalog metadata: a public, publisher-authored, installable definition of an integration’s config fields and secret slots. It is distinct from a connection instance on this page, which is the workspace- and environment-scoped binding of a definition to concrete config values and named secrets. Installing a package never creates a connection instance or copies a secret; an operator still creates the connection instance separately, against the installed definition, before a flow can use it.

Supported Secret Backends

Set ORQESTRA_SECRET_BACKEND on the runtime gateway.

Cloud deployments are not limited to provider-native secret managers. Vault is a valid backend in cloud deployments when your platform team operates Vault and has wired identity, network access, audit, backup, and rotation around it.

The Azure backend is refused in local and pentest environments. It requires the full namespace, workspace, and environment for every read; an unscoped or partially scoped credential_ref fails before contacting Key Vault. The runtime checks the stored scope tags before returning a value. A configured credential reference in MCP, Azure AI Search, or Azure Event Grid fails the call if resolution fails; inline input credentials are used only when no credential reference was configured.

Set ORQESTRA_SECRET_FALLBACK=env only when you intentionally want unresolved unscoped secrets to fall back to environment variables. Runtime requests that carry namespace, workspace, or environment scope fail closed instead of falling through to an unscoped backend.

Control Plane Secret Lifecycle

The control plane exposes workspace and environment secret CRUD backed by the configured secret service. Secret metadata can be listed, but values are only returned by an explicit reveal endpoint with audit logging.

Create a secret

curl -X POST "http://localhost:8000/v1/secrets?workspace_id=workspace-123&environment=dev" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "pinecone.api-key",
    "value": "secret-value"
  }'

List secret metadata

curl "http://localhost:8000/v1/secrets?workspace_id=workspace-123&environment=dev"

List responses include names and metadata, not secret values.

Update a secret

curl -X PUT "http://localhost:8000/v1/secrets/pinecone.api-key?workspace_id=workspace-123&environment=dev" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "rotated-secret-value"
  }'

Reveal a secret

curl "http://localhost:8000/v1/secrets/pinecone.api-key/reveal?workspace_id=workspace-123&environment=dev"

Reveal responses include no-store cache headers and create a secret.revealed audit event. Denied reveal attempts create secret.reveal_denied.

Delete a secret

curl -X DELETE "http://localhost:8000/v1/secrets/pinecone.api-key?workspace_id=workspace-123&environment=dev"

Secret Permissions

Reveal access should be narrow. Most workflows should bind or rotate a secret without exposing the value back to a browser or CLI session.

Connection Instance Lifecycle

Connection instances bind a workspace and release environment to a connection definition version, configuration values, and named secrets.

Create a connection instance

curl -X POST "http://localhost:8000/v1/connection-instances?workspace_id=workspace-123" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "pinecone-kb",
    "environment": "production",
    "display_name": "Pinecone Knowledge Base",
    "connection_definition_id": "pinecone-definition-id",
    "connection_definition_version_id": "pinecone-definition-version-id",
    "config": {
      "region": "us-east-1",
      "index": "support-kb"
    },
    "secret_bindings": {
      "api_key": "pinecone.api-key"
    }
  }'

The control plane validates that the definition version exists and that bound secret names exist in the connection instance’s workspace and environment secret store.

List and inspect connections

curl "http://localhost:8000/v1/connection-instances?workspace_id=workspace-123"
curl "http://localhost:8000/v1/connection-instances/{instance_id}?workspace_id=workspace-123"

The status is connected when all required config fields are populated and all required secret slots are bound. Otherwise it is setup_required.

Definition-version tool allowlists

Every new connector definition version must declare both tools_available_for_execution and tools_for_connection_establishment. The establishment list must be a subset of the execution list. If the definition has a saved-connection test policy, test.tool_name must appear in both lists. An empty list means no tool is allowed on that path; an absent list is rejected by current authoring contracts and denied by runtime as a defense in depth measure.

The check is independent of agent grants. Even if a workload or agent is mistakenly granted a tool, the credential cannot be resolved for that tool unless the connection’s pinned definition version also permits it. Saved connection tests apply the establishment list before reading Vault or opening a network connection.

Share a connection with exact principals

Owners can switch an instance between private and shared and manage active rules through the ACL routes:

curl -X PATCH "http://localhost:8000/v1/connection-instances/{instance_id}?workspace_id=owner-workspace" \
  -H "Content-Type: application/json" \
  -d '{"sharing_mode":"shared"}'
 
curl -X POST "http://localhost:8000/v1/connection-instances/{instance_id}/acl?workspace_id=owner-workspace" \
  -H "Content-Type: application/json" \
  -d '{"principal_ref":"service:runtime-a","effect":"allow"}'
 
curl -X DELETE "http://localhost:8000/v1/connection-instances/{instance_id}/acl/{rule_id}?workspace_id=owner-workspace"

Principal refs are exact canonical values such as user:alice@example.com or service:runtime-a; prefixes and wildcards do not match. No matching allow is a denial, and any matching deny overrides an allow. Sharing never crosses an organization boundary. Revocation takes effect on the next discovery, binding, or execution check; a release that was bound earlier does not retain access.

Owners receive principal_acl in list/detail responses, including [] when there are no active rules. Permitted consumers use GET /v1/connection-instances/shared; their projection omits principal_acl entirely and redacts config and secret bindings. A consumer cannot distinguish an inaccessible connection from a nonexistent one through detail or release-binding routes.

Test a saved connection

Connection definitions can declare a bounded HTTP reachability policy. For saved connection instances using those definitions, workspace admins can test the remote service through the control plane:

curl -X POST "http://localhost:8000/v1/connection-instances/{instance_id}/test?workspace_id=workspace-123"

The response reports one of reachable, auth_failed, unreachable, not_bound, or blocked_by_policy. It includes only diagnostic metadata such as the target host, HTTP status code, message, and check time. Secret values and secret binding names are never returned. Tests run through the shared egress guard with the connection definition’s allowlisted host, timeout, and response size bounds.

Update or delete a connection

curl -X PATCH "http://localhost:8000/v1/connection-instances/{instance_id}?workspace_id=workspace-123" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "environment": "us-east-1",
      "index": "support-kb-v2"
    }
  }'
 
curl -X DELETE "http://localhost:8000/v1/connection-instances/{instance_id}?workspace_id=workspace-123"

Python SDK

The SDK exposes connection instance operations.

from orqestra_sdk import OrqestraClient
 
async with OrqestraClient("http://localhost:8000", workspace_id="workspace-123") as client:
    connections = await client.connection_instances.list()
 
    created = await client.connection_instances.create(
        slug="pinecone-kb",
        environment="production",
        display_name="Pinecone Knowledge Base",
        connection_definition_id="pinecone-definition-id",
        connection_definition_version_id="pinecone-definition-version-id",
        config={"region": "us-east-1", "index": "support-kb"},
        secret_bindings={"api_key": "pinecone.api-key"},
        sharing_mode="shared",
    )
 
    rule = await client.connection_instances.add_acl_rule(
        created["instance_id"],
        principal_ref="service:runtime-a",
        effect="allow",
    )
    shared_with_me = await client.connection_instances.list_shared()
    owner_rules = await client.connection_instances.list_acl(created["instance_id"])
 
    await client.connection_instances.update(
        created["instance_id"],
        config={"region": "us-east-1", "index": "support-kb-v2"},
    )
 
    reachability = await client.connection_instances.test(created["instance_id"])
 
    await client.connection_instances.revoke_acl_rule(
        created["instance_id"], rule["rule_id"]
    )

Secret CRUD is currently documented through the HTTP API. Use SDK support only for surfaces exposed by your installed SDK version.

Runtime Secret Resolution

Flow steps can reference connection values through template expressions:

• Config values: {{ connections.pinecone-kb.config.environment }}
• Secret values: {{ connections.pinecone-kb.secrets.api_key }}

At execution time:

1. Release authoring accepts an owner connection or an ACL-permitted shared connection in the same organization and environment.
2. The execution-context aggregate re-evaluates the actual execution principal; earlier binding authority is not reused.
3. The control plane emits an execution-bound run pin for every logical slot.
4. The runtime validates every pin as an all-or-nothing set and builds the connection scope from the aggregate, without a fallback lookup.
5. Secret names resolve under the connection owner’s namespace, workspace, and environment—not the consumer workspace.
6. Immediately before a credential consumer runs, the runtime re-checks the requested tool against the pinned definition-version allowlist.
7. Secret values are redacted from execution details, traces, audit, and decision evidence.

The internal connection resolution surface returns definition content, config, workspace and namespace slugs, and secret binding names. It does not return secret values.

Runtime connection denials use bounded error discriminators. ACL or sharing denials return connection_resolution_denied with a reason and decision id; malformed or mismatched aggregates return connection_run_pin_invalid; an external mediated tool outside the connection allowlist returns tool_allowlist_denied. These responses do not include ACL contents, config, secret binding names, or secret values.

Definition Migration And Rollback

Allowlist fields belong to an immutable connector definition version. Publish a new version for an older definition that lacks them; do not mutate historical content. Built-in connector updates likewise use new seed versions. Until a release is rebound to the new version, a missing runtime allowlist fails closed.

The sharing migration is additive, with existing instances remaining private. Rolling back only the runtime or control plane while shared release bindings exist is unsafe because the older component cannot enforce the ACL and run-pin contract. Before such a rollback, switch affected connections to private, rebind releases to consumer-owned instances, and verify no active release depends on a shared connection. ACL revocation is not a substitute for that compatibility step.

Vault Setup

For a Vault-backed runtime:

export ORQESTRA_SECRET_BACKEND="vault"
export VAULT_ADDR="http://127.0.0.1:8200"
export VAULT_ROLE_ID="..."
export VAULT_SECRET_ID="..."

The runtime resolver expects HashiCorp Vault KV v2 with AppRole credentials. Control-plane secret APIs can store and retrieve workspace- and environment-scoped secrets through the Vault-backed secret service.

Cloud Deployment Guidance

Cloud deployments can use Vault or a provider-native backend:

• Vault: ORQESTRA_SECRET_BACKEND=vault
• Azure Key Vault: ORQESTRA_SECRET_BACKEND=azure_key_vault
• AWS Secrets Manager: ORQESTRA_SECRET_BACKEND=aws_secrets_manager
• Google Secret Manager: ORQESTRA_SECRET_BACKEND=gcp_secret_manager

Whichever backend you choose, keep identity and network access narrow. Runtime workloads should be able to read only the secret paths they need, while administrative control-plane surfaces should retain audit visibility for secret creation, rotation, reveal, and deletion.

Audit And Redaction

Secret and connection mutations emit audit events:

• secret.created
• secret.updated
• secret.deleted
• secret.revealed
• secret.reveal_denied
• connection_instance.created
• connection_instance.updated
• connection_instance.deleted

Connection audit records include binding slot names, not secret values. Runtime execution records redact secret values as ***REDACTED***.

Failure Modes

Operational Workflow

1. Choose the backend per environment: Vault, a provider-native cloud secret manager, environment variables, or static config for tests.
2. Create workspace and environment secrets before creating connection instances.
3. Bind connection instances to definition versions and required secret slots.
4. Validate flow references in the editor or API.
5. Execute with a runtime backend that can resolve the same secret names.
6. Rotate secrets through update APIs and watch audit logs for reveal activity.