--- title: "Create a connector instance" method: POST path: "/connectors" tags: ["Connectors"] --- # Create a connector instance `POST /connectors` Creates the connector instance and its backing Party. The request must include the connector identity data needed to bind or create the Party identity up front. Identifiers must be supplied inside an identity. ## Request body - ConnectorInstanceCreateRequest — Request to register a connector instance and create or link the backing Party. Identity data is required so the connector aggregate is Party-backed at creation time. - `displayName` string, required — Human-readable name shown in administrative UIs and audit trails. - `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. - `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. - `partyId` string, uuid — Existing Party model identifier. - `supportedRoles` DataFlowRole[], required — Data-flow roles supported by this connector instance. - `supportedOperations` OperationKind[] — Logical operations this connector instance can perform. - `identities` ConnectorIdentityInput[], required — Identities assigned to the connector Party. Exactly one identity must be marked as default. Each identity must reference an existing identity or include at least one identifier. - `identityRole` string, required — Role of this Identity for the connector Party, for example technical-account, issuer, relying-party, or external-system. - `displayName` string — Display name for the connector identity. - `existingIdentityId` string, uuid — Existing Identity model identifier. - `isDefault` boolean — Whether this identity is the default identity for connector operations that do not select a specific identity. - `identifiers` ConnectorIdentifierInput[] — Identifiers attached to this Identity. Identifiers are not attached directly to the connector. - `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. - `endpoints` ConnectorEndpointInput[] — Runtime endpoints exposed or consumed by this connector instance. - `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. - `credentials` ConnectorCredentialRef[] — Credential references used by the connector. Secret values are never sent inline. - `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[] — Platform settings bindings that hold non-secret connector configuration and secret reference prefixes. - `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. - `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. - `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. ## Response `201` Connector instance created. - 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 - `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)