---
title: "Get a connector instance"
method: GET
path: "/connectors/{connectorInstanceId}"
tags: ["Connectors"]
---

# Get a connector instance

`GET /connectors/{connectorInstanceId}`

Reads one connector instance, including its backing Party id, assigned identities,
endpoint references, credential references, settings bindings, and default policies.
Secret values are never returned.

## Path parameters

- `connectorInstanceId` string, uuid, required — Stable platform identifier for a configured connector instance.

## Response `200`

Connector instance.

- ConnectorInstance — Registered connector instance with its own stable id and a backing Party id. Runtime credentials are represented only as references.
  - `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.

## Other responses

- `401` — Authentication is required.
- `404` — The requested resource was not found.

---

[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)