Connections

Connections gives applications controlled access to company systems. The database integration separates connection metadata, credential submission, validation, activation and permission to execute queries.

Connection lifecycle

1. Create a draft identifying the intended database connection.
2. Prepare a candidate configuration and submit its credential through the designated protected credential flow.
3. Validate the candidate and inspect its health.
4. Propose and approve the configuration change where required, then activate the approved candidate.
5. Grant the intended query or introspection capability to the authorized caller.

A listed connection can still require activation or additional execution permission. Applications should handle those states explicitly before attempting a query.

Availability

The database management contract includes listing, candidate validation and governed configuration changes. Execution has a separate authorization and configuration contract. Confirm the installed adapter, network access and enabled operations before onboarding a database. Connector support is specific to the installation.

Quickstart — list database connections

Use the enabled product API origin from an approved same-origin integration. First complete browser sign-in. Supply the returned CSRF value and the current tab context. The browser sends its session cookie and Origin header automatically.

const response = await fetch(
  '/primero.connections.v1.DatabaseManagementService/ListDatabaseConnections',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Connect-Protocol-Version': '1',
      'X-Primia-Context': context,
      'X-Primia-CSRF': csrf,
    },
    body: JSON.stringify({ limit: 20 }),
  },
)
if (!response.ok) throw new Error('Connection listing failed')
const { connections } = await response.json()

An empty successful response can be {"connections":[]}. This operation reads connection metadata. Credential submission uses its own authorized flow.

Errors and next steps

A denied read requires checking the current session, selected workspace and operation permission. An unavailable route requires checking that your frontend forwards this exact Connect route to the enabled API host. Review the connection’s status before moving on to candidate validation or query execution.