v2

latestOpenAPI 3.0.4Apache 2.0raw.githubusercontent.com2026-07-1754198241.7 KB

Connectors

Create a connector instance

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.

post/connectors

Request body

displayNamestring required

Human-readable name shown in administrative UIs and audit trails.

descriptionstring

Operational purpose of the connector instance.

connectorTypestring 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.

partyIdstring uuid

Existing Party model identifier.

supportedRolesDataFlowRole[] required

Data-flow roles supported by this connector instance.

supportedOperationsOperationKind[]

Logical operations this connector instance can perform.

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.

metadataStringMap

Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data.

Example request

{
  "displayName": "Workday employee profile API",
  "description": "Reads employee profile attributes used for employee credential issuance.",
  "connectorType": "http.openapi",
  "managementMode": "EXTERNAL",
  "runtimeMode": "REMOTE_AGENT",
  "supportedRoles": [
    "SOURCE"
  ],
  "supportedOperations": [
    "READ",
    "QUERY",
    "DISCOVER"
  ],
  "identities": [
    {
      "identityRole": "external-system",
      "displayName": "Workday tenant acme-prod",
      "isDefault": true,
      "identifiers": [
        {
          "identifierType": "DNS_NAME",
          "value": "hr.example.com",
          "isPrimary": true,
          "isVerified": true
        },
        {
          "identifierType": "SYSTEM_ID",
          "value": "workday:acme-prod",
          "isPrimary": false,
          "isVerified": true
        }
      ]
    }
  ],
  "endpoints": [
    {
      "endpointRole": "data",
      "accessProtocol": "HTTPS",
      "uri": "https://hr.example.com/api/v1",
      "isPrimary": true
    }
  ],
  "credentials": [
    {
      "bindingMode": "SECRET_REF",
      "secretRef": "secret://tenant/acme/connectors/workday/oauth-client",
      "credentialType": "oauth2-client",
      "label": "Workday OAuth client"
    }
  ],
  "configBindings": [
    {
      "settingsScope": "service-instance",
      "settingsKeyPrefix": "connector.workday.acme-prod"
    }
  ],
  "defaultAccessProtocol": "HTTPS",
  "metadata": {
    "owner_team": "people-ops"
  }
}

Response

Connector instance created.

connectorInstanceIdstring uuid required

Stable platform identifier for a configured connector instance.

partyIdstring uuid required

Party identifier assigned to the connector instance.

displayNamestring required

Human-readable name of the connector instance.

descriptionstring

Operational purpose of the connector instance.

connectorTypestring 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.

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.

supportedRolesDataFlowRole[] required

supportedOperationsOperationKind[]

metadataStringMap

Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data.

createdAtstring date-time required

Creation timestamp.

updatedAtstring date-time required

Last update timestamp.

Example response

{
  "connectorInstanceId": "3f6f4f46-24fb-4c35-a7a4-bc6c7f7861f5",
  "partyId": "f9c97b4e-e756-4b70-b230-6f1d9f81b426",
  "displayName": "Workday employee profile API",
  "description": "Reads employee profile attributes used for employee credential issuance.",
  "connectorType": "http.openapi",
  "lifecycleStatus": "ACTIVE",
  "managementMode": "EXTERNAL",
  "runtimeMode": "REMOTE_AGENT",
  "defaultAccessProtocol": "HTTPS",
  "supportedRoles": [
    "SOURCE"
  ],
  "supportedOperations": [
    "READ",
    "QUERY",
    "DISCOVER"
  ],
  "identities": [
    {
      "identityId": "3a5cf979-2d89-4057-a721-c7ab884f0c68",
      "identityRole": "external-system",
      "displayName": "Workday tenant acme-prod",
      "isDefault": true,
      "identifiers": [
        {
          "identifierId": "6b1c4c89-dfe0-4ce2-b8a4-2e1d57343a6c",
          "identifierType": "DNS_NAME",
          "value": "hr.example.com",
          "isPrimary": true,
          "isVerified": true
        }
      ]
    }
  ],
  "endpoints": [
    {
      "endpointId": "27d8bfc5-6c75-4e4e-a78a-63ad7a924cb1",
      "endpointRole": "data",
      "accessProtocol": "HTTPS",
      "uri": "https://hr.example.com/api/v1",
      "isPrimary": true
    }
  ],
  "credentials": [
    {
      "bindingMode": "SECRET_REF",
      "secretRef": "secret://tenant/acme/connectors/workday/oauth-client",
      "credentialType": "oauth2-client",
      "label": "Workday OAuth client"
    }
  ],
  "configBindings": [
    {
      "settingsScope": "service-instance",
      "settingsKeyPrefix": "connector.workday.acme-prod"
    }
  ],
  "metadata": {
    "owner_team": "people-ops"
  },
  "createdAt": "2026-06-18T08:30:00Z",
  "updatedAt": "2026-06-18T08:45:00Z"
}