---
title: "List connector instances"
method: GET
path: "/connectors"
tags: ["Connectors"]
---

# List connector instances

`GET /connectors`

Lists connector instances registered for the tenant. Use this endpoint to find durable
integration endpoints by connector family, data-flow role, or logical operation support.
A connector instance is not itself a resource shape; resource descriptors and operation
bindings describe what the connector can read or write.

## Query parameters

- `connectorType` string — Extensible connector family identifier. This names the connector implementation or adapter family, not the transport, resource kind, or representation.
- `role` 'SOURCE' | 'DESTINATION' — How a connector participates in data movement. Use SOURCE for reads and DESTINATION for writes. Connectors that support both roles declare both values in supportedRoles.
- `operationKind` 'READ' | 'WRITE' | 'UPDATE' | 'DELETE' | 'UPSERT' | 'QUERY' | 'SEARCH' | 'IMPORT' | 'EXPORT' | 'INVOKE' | 'DISCOVER' | 'VALIDATE' — Reusable operation taxonomy shared by connectors, inventory, policy, and workflows. The operation kind is logical; connector-local details live in operationName.
- `page` integer
- `size` integer

## Response `200`

Paged connector instances.

- ConnectorInstancePage — Page of connector instances.
  - `data` ConnectorInstance[], required
    - `connectorInstanceId` string, uuid, required — Stable platform identifier for a configured connector instance.
    - `partyId` string, uuid, required — Party identifier assigned to the connector instance.
    - `displayName` string, required — Human-readable name of the connector instance.
    - `description` string — Operational purpose of the connector instance.
    - `connectorType` string, required — Extensible connector family identifier. This names the connector implementation or adapter family, not the transport, resource kind, or representation.
    - `lifecycleStatus` 'DRAFT' | 'ACTIVE' | 'SUSPENDED' | 'RETIRED', required — Lifecycle state of a connector instance in the connector registry.
    - `managementMode` 'MANAGED' | 'EXTERNAL' — Indicates whether the platform manages connector runtime/configuration or references an externally managed system. Runtime placement is described separately by runtimeMode.
    - `runtimeMode` 'HOSTED' | 'REMOTE_AGENT' | 'EXTERNAL_CALLBACK' — Indicates where execution happens when a connector operation is invoked.
    - `defaultAccessProtocol` 'HTTP' | 'HTTPS' | 'JDBC' | 'ODBC' | 'SFTP' | 'FILE' | 'S3' | 'AZURE_BLOB' | 'GCS' | 'KAFKA' | 'AMQP' | 'MQTT' | 'OIDC' | 'DIDCOMM' | 'VAULT' | 'INTERNAL' | 'CUSTOM' — Transport or access protocol. This is intentionally separate from ResourceKind and RepresentationKind: for example, CSV data can be read over HTTPS, S3, SFTP, FILE, or VAULT.
    - `supportedRoles` DataFlowRole[], required
    - `supportedOperations` OperationKind[]
    - `identities` ConnectorIdentity[]
      - `identityId` string, uuid, required — Existing Identity model identifier.
      - `identityRole` string, required — Role of this Identity for the connector Party.
      - `displayName` string — Display name for the connector identity.
      - `isDefault` boolean, required — Whether this is the default identity for the connector.
      - `identifiers` ConnectorIdentifier[] — Identifiers attached to this Identity.
        - `identifierType` string, required — Existing Party Identifier type, for example DNS_NAME, URL, DID, OIDC_ISSUER, EMAIL, CLIENT_ID, or SYSTEM_ID.
        - `value` string, required — Identifier value.
        - `isPrimary` boolean — Whether this is the preferred identifier for its type on the Identity.
        - `isVerified` boolean — Whether the platform has verified or administratively accepted this identifier.
        - `metadata` StringMap — Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data.
        - `identifierId` string, uuid, required — Existing Identifier model identifier.
    - `endpoints` ConnectorEndpoint[]
      - `endpointRole` string — Role of this endpoint, for example management, data, discovery, callback, token, or webhook.
      - `accessProtocol` 'HTTP' | 'HTTPS' | 'JDBC' | 'ODBC' | 'SFTP' | 'FILE' | 'S3' | 'AZURE_BLOB' | 'GCS' | 'KAFKA' | 'AMQP' | 'MQTT' | 'OIDC' | 'DIDCOMM' | 'VAULT' | 'INTERNAL' | 'CUSTOM', required — Transport or access protocol. This is intentionally separate from ResourceKind and RepresentationKind: for example, CSV data can be read over HTTPS, S3, SFTP, FILE, or VAULT.
      - `uri` string — Endpoint URI, JDBC URL, bucket URI, file root, queue address, or connector-specific locator.
      - `isPrimary` boolean — Whether this endpoint is the default endpoint for its role.
      - `metadata` StringMap — Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data.
      - `endpointId` string, uuid, required — Stable endpoint identifier.
    - `credentials` ConnectorCredentialRef[]
      - `bindingMode` 'SECRET_REF' | 'VAULT_KEY' | 'EXTERNAL_SECRET_REF', required — How credentials are referenced. Secret values are never sent inline through this API.
      - `credentialId` string, uuid — Optional platform credential identifier when credentials are first-class resources.
      - `secretRef` string — Opaque platform secret reference, not a secret value.
      - `externalSecretRef` string — External secret-manager reference when the platform does not own the secret.
      - `credentialType` string — Connector-specific credential type, for example oauth2-client, api-key, username-password, ssh-key, certificate, or service-account.
      - `label` string — Administrative label for the credential reference.
      - `keyAlias` string — Optional KMS or vault key alias used by the connector.
      - `metadata` StringMap — Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data.
    - `configBindings` ConnectorConfigBindingRef[]
      - `configBindingId` string, uuid — Stable settings/configuration binding identifier.
      - `settingsScope` string — Platform settings scope used by the connector, for example tenant, service, instance, or route.
      - `settingsKeyPrefix` string — Prefix under which connector settings are stored.
      - `metadata` StringMap — Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data.
    - `defaultEgressPolicy` EgressPolicy — Network and payload egress limits for connector operations. This is the connector policy hook for SSRF protection, tenant boundary checks, and later semantic/compliance checks. Runtime adapters should resolve names before connecting and pass the resolved address to the evaluator when DNS pinning is enabled.
      - `allowedHosts` string[] — Hostnames or wildcard host patterns the connector is allowed to contact. Use `*.example.com` for one-or-more subdomains.
      - `blockedHosts` string[] — Hostnames or wildcard host patterns that are always denied, even when they also match an allowed host pattern.
      - `allowedCidrs` string[] — IPv4 CIDR ranges the connector may contact when the target or resolved address is an IP address.
      - `allowedProtocols` AccessProtocol[] — Access protocols allowed by this connector or operation.
      - `allowedPorts` integer[] — Network ports allowed by this connector or operation. Empty means protocol defaults are allowed unless another policy blocks the target.
      - `blockPrivateNetworks` boolean — Whether private, loopback, link-local, local, multicast, and cloud metadata targets are denied by default.
      - `pinResolvedAddress` boolean — Whether runtime adapters should connect to the already-validated resolved address to reduce DNS rebinding risk.
      - `maxPayloadBytes` integer — Maximum allowed request or response payload size in bytes.
      - `requiresTenantBoundary` boolean — Whether route execution must enforce tenant boundary checks before egress.
      - `metadata` StringMap — Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data.
    - `defaultMaterializationPolicy` MaterializationPolicy — Policy for retaining, caching, indexing, or mirroring data touched by connector routes.
      - `mode` 'NONE' | 'CACHE' | 'PERSIST' | 'MIRROR' | 'INDEX' — How, if at all, connector data may be retained or projected into platform storage.
      - `ttlSeconds` integer — Time to live for materialized data in seconds.
      - `storageResourceDescriptorId` string, uuid — Stable identifier for a described external or internal resource shape.
      - `retention` RetentionSpec — Retention metadata used by governance and future compliance checks. It can be applied to fields, resources, materialized data, or dead-letter payloads.
        - `purpose` string — Processing purpose.
        - `legalBasis` string — Legal or contractual basis for retention.
        - `retentionPeriod` string — ISO-8601 duration, for example P30D or P7Y.
        - `deleteAction` 'DELETE' | 'ANONYMIZE' | 'PSEUDONYMIZE' | 'TOMBSTONE' | 'REVIEW' — Action to apply when retention expires or deletion is required by policy.
        - `metadata` StringMap — Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data.
      - `metadata` StringMap — Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data.
    - `metadata` StringMap — Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data.
    - `createdAt` string, date-time, required — Creation timestamp.
    - `updatedAt` string, date-time, required — Last update timestamp.
  - `pagination` Page, required — Pagination metadata emitted with each paged response under the `pagination` property.
    - `limit` integer, required — Maximum number of records requested for this page.
    - `offset` integer, required — Zero-based offset of the first record in this page.
    - `page` integer, required — Zero-based page index derived from offset and limit.
    - `size` integer, required — Effective page size.
    - `total` integer, required — Total number of matching records.
    - `totalPages` integer, required — Total number of available pages.
    - `hasMore` boolean, required — Whether another page is available after this page.

## Other responses

- `400` — Validation error.
- `401` — Authentication is required.

---

[API](https://skmtc.net/sphereon-opensource/apis/connector-integration-profile-api.md) · [All operations](https://skmtc.net/sphereon-opensource/apis/connector-integration-profile-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sphereon-opensource/connector-integration-profile-api/versions/60cb8c70871b/schema)