Set up a Fabric OneLake integration as an external data source

The features described in this article are in public preview and may change. The Transformations external data sources API is beta.

Before you start

On Microsoft Fabric

Requirement	Detail
Lakehouse Delta tables	Tables under `Tables/`, optionally `Tables/{schema}/{table}`.
Entra ID app	Service principal with application (client) ID, directory (tenant) ID, and client secret.
Role	At least Contributor on the workspace or lakehouse. Viewer cannot read through the OneLake API.
Tenant setting	Allow service principals to use Fabric APIs.
Network	Transformation compute must reach `onelake.dfs.fabric.microsoft.com`.

Fabric GUIDs

Use GUIDs, not friendly names.

Field	Where to find it
`workspaceId`	Workspace → Workspace settings → Workspace ID
`containerId`	Lakehouse → Lakehouse settings → Item ID

You can also copy GUIDs from the table ABFSS path or the browser URL.

On CDF

Use a CDF token for API calls. That identity is separate from the Fabric service principal.

Capability	Actions	Needed for
`transformationsExternalDataSourcesAcl`	`WRITE`	Register, update, or delete
`transformationsExternalDataSourcesAcl`	`READ`	List
`transformationsExternalDataSourcesAcl`	`USE`	Run transformations or queries that reference the source
`transformationsAcl`	`READ`, `WRITE`	Create and run transformations
Destination space capabilities	Read/write as needed	Write instances to your data model

Example scope for all sources in the project:

{
  "capabilities": [
    {
      "transformationsExternalDataSourcesAcl": {
        "actions": ["READ", "WRITE", "USE"],
        "scope": { "all": {} }
      }
    },
    {
      "transformationsAcl": {
        "actions": ["READ", "WRITE"],
        "scope": { "all": {} }
      }
    }
  ]
}

To limit access, set dataSetId on the source and use datasetScope on the capability.

Register the external data source

Set base values (replace placeholders):

export CDF_CLUSTER="westeurope-1"
export CDF_PROJECT="my-project"
export CDF_TOKEN="<cdf-access-token>"
export CDF_BASE="https://${CDF_CLUSTER}.cognitedata.com/api/v1/projects/${CDF_PROJECT}"

Create the Fabric service principal

In Microsoft Entra ID, create or select an app registration, create a client secret, and grant the principal at least Contributor on the Fabric workspace.

Grant CDF capabilities

Add the capabilities above to the group used by the identity that calls the API and runs transformations.

curl -sS -X POST "${CDF_BASE}/transformations/externaldata" \
  -H "Authorization: Bearer ${CDF_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "externalId": "my-fabric-source",
        "name": "Fabric - production lakehouse",
        "format": "one_lake",
        "dataSetId": null,
        "settings": {
          "credentials": {
            "clientId": "'"${FABRIC_CLIENT_ID}"'",
            "tenantId": "'"${FABRIC_TENANT_ID}"'",
            "clientSecret": "'"${FABRIC_CLIENT_SECRET}"'"
          },
          "locationDescription": {
            "workspaceId": "'"${FABRIC_WORKSPACE_ID}"'",
            "containerId": "'"${FABRIC_CONTAINER_ID}"'"
          }
        }
      }
    ]
  }'

format must be "one_lake". Success returns 201. clientSecret is never returned. Posting the same externalId again upserts; include the secret on every update.

Verify usability

curl -sS -X POST "${CDF_BASE}/transformations/externaldata/usability" \
  -H "Authorization: Bearer ${CDF_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "externalId": "my-fabric-source" }'

A usable source returns usableVersion. If that field is missing, check that the source exists, your identity has USE (and dataset scope if set), and the Fabric principal can reach the lakehouse.

Manage sources

Operation	Method and path	Capability
Register or update	`POST /transformations/externaldata`	`WRITE`
List	`GET /transformations/externaldata`	`READ`
Delete	`POST /transformations/externaldata/delete`	`WRITE`
Verify	`POST /transformations/externaldata/usability`	`USE`

Full schemas: Transformation external data sources and the beta OpenAPI tag.

Data engineering

Set up a Fabric OneLake integration as an external data source

Before you start

On Microsoft Fabric

Fabric GUIDs

On CDF

Register the external data source

Manage sources

Next steps

​Before you start

​On Microsoft Fabric

​Fabric GUIDs

​On CDF

​Register the external data source

​Manage sources

​Next steps

Before you start

On Microsoft Fabric

Fabric GUIDs

On CDF

Register the external data source

Manage sources

Next steps