> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up a Fabric OneLake integration as an external data source

> Register Microsoft Fabric OneLake credentials and location so Transformations can read Delta tables with ext_onelake.

<Warning>
  The features described in this article are in [public preview](/cdf/product_feature_status#public-preview) and may change. The Transformations external data sources API is [beta](/api-reference/concepts/20230101-beta/transformation-external-data).
</Warning>

Register a Fabric OneLake integration as an **external data source** with the Transformations API, then use it in SQL.

## 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:

```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
{
  "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):

```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
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}"
```

<Steps>
  <Step title="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.
  </Step>

  <Step title="Grant CDF capabilities">
    Add the [capabilities above](#on-cdf) to the group used by the identity that calls the API and runs transformations.
  </Step>

  <Step title="Register the source">
    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    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.
  </Step>

  <Step title="Verify usability">
    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    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.
  </Step>
</Steps>

## 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](/api-reference/concepts/20230101-beta/transformation-external-data) and the [beta OpenAPI tag](https://api-docs.cognite.com/20230101-beta/tag/Transformation-External-Data-Sources).

## Next steps

* [Read Fabric OneLake data in transformations](/cdf/integration/guides/transformation/read_fabric_onelake)
* [Troubleshoot Fabric OneLake in Transformations](/cdf/integration/guides/transformation/troubleshoot_fabric_onelake)