Tractusx EDC

Interact with Tractus-X EDC (Eclipse Data Connector) control plane API v3 for managing assets, contract negotiations, policies, and data transfers.

Security Scan

The skill is an instruction-only wrapper around the Tractus‑X EDC control plane v3 API; its required environment variables and runtime instructions align with its stated purpose, with only a small documentation mismatch about whether the API key is optional.

Purpose & Capability

Name/description describe interacting with an EDC control plane and the skill only requests EDC_CONTROL_PLANE_URL and EDC_API_KEY, which are exactly what an API wrapper would need. No unrelated credentials or binaries are requested. Minor inconsistency: README/SKILL.md text says EDC_API_KEY is optional depending on connector config, but the metadata lists it as a required env var.

Instruction Scope

SKILL.md contains curl examples and endpoint paths for asset, policy, contract, negotiation, transfer, and EDR management and instructs using Bash/curl against the configured control plane. It does not instruct reading unrelated files, other environment variables, or exfiltrating data to third‑party endpoints beyond the configured control plane or connector addresses shown in examples.

Install Mechanism

No install spec and no code files — instruction-only skill. This minimizes on-disk code risk; runtime behavior depends on executing curl (network calls), which is expected for an API integration.

Credentials

Only EDC_CONTROL_PLANE_URL and EDC_API_KEY are declared, which is proportionate. Note the documentation contradiction: SKILL.md/README say EDC_API_KEY may be optional, but the skill metadata marks it required; clarify whether an API key is mandatory for your deployment before supplying one.

Persistence & Privilege

Skill is not forced always-on and uses default autonomous invocation behavior. It does not request system-level persistence or modify other skills. Autonomous invocation is normal for skills — combine with least-privilege API keys if you enable autonomous actions.

Assessment

This skill is an instruction-only API wrapper for the Tractus‑X EDC control plane and appears to do what it claims. Before installing: 1) Confirm whether your EDC deployment requires an API key — metadata requires EDC_API_KEY but docs say it may be optional. 2) Only provide an API key scoped with least privilege (avoid giving a key that can delete/change all assets if not needed). 3) Be aware the skill's curl commands include destructive operations (DELETE, PUT, contract/transfer initiation) — running the skill with an unrestricted key can modify or transfer data. 4) Prefer testing against a staging connector first, and monitor logs/requests on the control plane. 5) If you need the agent to act autonomously, consider restricting the API key's capabilities or disabling autonomous invocation for this skill. If you want, ask the maintainer to correct the documentation mismatch about whether EDC_API_KEY is optional.

Tractus-X EDC Connector Skill (v3 API)

Use this skill to interact with a Tractus-X EDC (Eclipse Data Connector) control plane using the v3 API.

Configuration

Set these environment variables:

• EDC_CONTROL_PLANE_URL - Base URL of the EDC control plane (e.g., http://localhost:9192)
• EDC_API_KEY - API key for authentication (optional, depends on connector config)

API Base URL

${EDC_CONTROL_PLANE_URL}/v3

Core Operations

1. Assets Management (v3)

Create Asset:

curl -X POST "${EDC_CONTROL_PLANE_URL}/v3/assets" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${EDC_API_KEY}" \
  -d '{
    "properties": {
      "id": "asset-id",
      "name": "Asset Name",
      "contentType": "application/json",
      "description": "Data asset description"
    },
    "dataAddress": {
      "type": "HttpData",
      "baseUrl": "https://provider.example.com/data",
      "proxyBody": true,
      "proxyPath": true
    }
  }'

Update Asset:

curl -X PUT "${EDC_CONTROL_PLANE_URL}/v3/assets" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${EDC_API_KEY}" \
  -d '{
    "properties": {
      "id": "asset-id",
      "name": "Updated Asset Name"
    }
  }'

List Assets:

curl -X POST "${EDC_CONTROL_PLANE_URL}/v3/assets/request" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${EDC_API_KEY}" \
  -d '{
    "filterExpression": [],
    "range": {"from": 0, "to": 100}
  }'

Get Asset:

curl -X GET "${EDC_CONTROL_PLANE_URL}/v3/assets/{id}" \
  -H "X-Api-Key: ${EDC_API_KEY}"

Delete Asset:

curl -X DELETE "${EDC_CONTROL_PLANE_URL}/v3/assets/{id}" \
  -H "X-Api-Key: ${EDC_API_KEY}"

2. Policy Definitions (v3)

List Policies:

curl -X POST "${EDC_CONTROL_PLANE_URL}/v3/policydefinitions/request" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${EDC_API_KEY}" \
  -d '{"filterExpression": [], "range": {"from": 0, "to": 100}}'

3. Contract Definitions (v3)

Create Contract Definition:

curl -X POST "${EDC_CONTROL_PLANE_URL}/v3/contractdefinitions" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${EDC_API_KEY}" \
  -d '{
    "id": "contract-def-id",
    "accessPolicyId": "policy-id",
    "contractPolicyId": "policy-id",
    "assetsSelector": [{
      "operandLeft": "https://w3id.org/edc/v0.0.1/ns/id",
      "operator": "=",
      "operandRight": "asset-id"
    }]
  }'

Update Contract Definition:

curl -X PUT "${EDC_CONTROL_PLANE_URL}/v3/contractdefinitions" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${EDC_API_KEY}" \
  -d '{
    "id": "contract-def-id",
    "accessPolicyId": "policy-id",
    "contractPolicyId": "policy-id",
    "assetsSelector": [{
      "operandLeft": "https://w3id.org/edc/v0.0.1/ns/id",
      "operator": "=",
      "operandRight": "asset-id"
    }]
  }'

List Contract Definitions:

curl -X POST "${EDC_CONTROL_PLANE_URL}/v3/contractdefinitions/request" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${EDC_API_KEY}" \
  -d '{"filterExpression": [], "range": {"from": 0, "to": 100}}'

4. Contract Negotiations (v3)

Initiate Negotiation:

curl -X POST "${EDC_CONTROL_PLANE_URL}/v3/contractnegotiations" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${EDC_API_KEY}" \
  -d '{
    "connectorId": "provider-connector-id",
    "connectorAddress": "http://provider-connector:9194/protocol/dsp",
    "offer": {
      "assetId": "asset-id",
      "offerId": "offer-id:1",
      "policy": {
        "permissions": [{
          "target": "default",
          "action": {"type": "USE"},
          "constraints": []
        }]
      }
    }
  }'

Query Negotiations:

curl -X POST "${EDC_CONTROL_PLANE_URL}/v3/contractnegotiations/request" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${EDC_API_KEY}" \
  -d '{"filterExpression": [], "range": {"from": 0, "to": 100}}'

Get Contract Agreement for Negotiation:

curl -X GET "${EDC_CONTROL_PLANE_URL}/v3/contractnegotiations/{id}/agreement" \
  -H "X-Api-Key: ${EDC_API_KEY}"

5. Contract Agreements (v3)

Get Contract Agreement:

curl -X GET "${EDC_CONTROL_PLANE_URL}/v3/contractagreements/{id}" \
  -H "X-Api-Key: ${EDC_API_KEY}"

Get Retired Agreements:

curl -X POST "${EDC_CONTROL_PLANE_URL}/v3/contractagreements/retirements/request" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${EDC_API_KEY}"

6. Transfer Processes (v3)

Initiate Transfer:

curl -X POST "${EDC_CONTROL_PLANE_URL}/v3/transferprocesses" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${EDC_API_KEY}" \
  -d '{
    "protocol": "dsp",
    "connectorId": "provider-connector-id",
    "connectorAddress": "http://provider-connector:9194/protocol/dsp",
    "contractId": "contract-agreement-id",
    "assetId": "asset-id",
    "managedResources": true,
    "dataDestination": {
      "type": "HttpProxy",
      "baseUrl": "http://consumer-backend:8080/data"
    }
  }'

Suspend Transfer:

curl -X POST "${EDC_CONTROL_PLANE_URL}/v3/transferprocesses/{id}/suspend" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${EDC_API_KEY}" \
  -d '{"reason": "Suspension reason"}'

7. EDR (Endpoint Data Reference) Management (v3)

Initiate EDR Negotiation:

curl -X POST "${EDC_CONTROL_PLANE_URL}/v3/edrs" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${EDC_API_KEY}" \
  -d '{
    "connectorId": "provider-connector-id",
    "connectorAddress": "http://provider-connector:9194/protocol/dsp",
    "offer": {
      "assetId": "asset-id",
      "offerId": "offer-id:1",
      "policy": {
        "permissions": [{
          "target": "default",
          "action": {"type": "USE"},
          "constraints": []
        }]
      }
    }
  }'

Get EDR Data Address:

curl -X GET "${EDC_CONTROL_PLANE_URL}/v3/edrs/{transferProcessId}/dataaddress" \
  -H "X-Api-Key: ${EDC_API_KEY}"

8. Business Partner Groups (v3)

Resolve All Groups:

curl -X GET "${EDC_CONTROL_PLANE_URL}/v3/business-partner-groups/groups" \
  -H "X-Api-Key: ${EDC_API_KEY}"

Resolve Groups for BPN:

curl -X GET "${EDC_CONTROL_PLANE_URL}/v3/business-partner-groups/{bpn}" \
  -H "X-Api-Key: ${EDC_API_KEY}"

Delete BPN Entry:

curl -X DELETE "${EDC_CONTROL_PLANE_URL}/v3/business-partner-groups/{bpn}" \
  -H "X-Api-Key: ${EDC_API_KEY}"

9. Health Checks

Health Check:

curl -X GET "${EDC_CONTROL_PLANE_URL}/check/health"

Startup Check:

curl -X GET "${EDC_CONTROL_PLANE_URL}/check/startup"

Workflow: Complete Data Exchange

1. Provider Side:

   • Create Asset with data address
   • Create Policy definition
   • Create Contract definition linking asset to policy

2. Consumer Side:

   • Initiate Contract Negotiation
   • Query negotiations to track state
   • Get Contract Agreement from negotiation
   • Initiate Transfer Process
   • Suspend/resume transfer as needed
   • Get EDR data address for actual data access

Common States

Contract Negotiation States (from negotiation object)

• REQUESTING - Initial request sent
• OFFERED - Offer received
• ACCEPTED - Offer accepted
• AGREED - Agreement reached
• VERIFIED - Agreement verified
• TERMINATED - Negotiation ended

Transfer Process States

• INITIAL - Transfer initiated
• PROVISIONING - Resources being provisioned
• PROVISIONED - Resources ready
• REQUESTING - Request sent to provider
• STARTED - Transfer started
• SUSPENDED - Transfer paused
• COMPLETED - Transfer finished
• TERMINATED - Transfer ended
• ERROR - Transfer failed

Error Handling

Errors return with status codes:

• 400 - Request malformed
• 404 - Resource not found
• 409 - Conflict (e.g., asset already exists)
• 500 - Internal server error

Response format:

[{ "message": "Error description", "path": "field/path", "invalidValue": "bad-value" }]

OpenAPI Reference

Full API specification: https://eclipse-tractusx.github.io/api-hub/tractusx-edc/0.12.0/control-plane/control-plane.yaml