Configure Power BI tenant settings
Enable the four Power BI tenant settings Atlan needs, grant the security group workspace access, and understand the Scanner API trade-off.
Atlan reads Power BI metadata through tenant settings your admin enables; configure the four required settings below.
Performed by your Power BI / Fabric admin · about 10 minutes, plus 15-30 minutes of propagation. Four independent settings, all four are required, and each must be scoped to your security group.
Tenant settings
In the Power BI Admin portal → Tenant settings, enable each of these and add sg-atlan-powerbi under "Specific security groups":
| Setting | Section | What breaks without it |
|---|---|---|
| Service principals can call Fabric public APIs (Microsoft's REST docs call the same toggle "Service principals can use Fabric APIs"; formerly "Allow service principals to use Power BI APIs") | Developer settings | The workspace dropdown in Atlan stays empty or throws 400s; the workspace-permissions preflight fails with 401. Column and measure lineage to pages produces nothing. The most commonly missed setting, admin API access doesn't cover it. |
| Service principals can access read-only admin APIs | Admin API settings | The metadata-scan preflight fails with PowerBINotAuthorizedException 401; tenant-wide discovery is impossible. |
| Enhance admin APIs responses with detailed metadata | Admin API settings | Assets crawl but tables, columns, and measures are missing. |
| Enhance admin APIs responses with DAX and mashup expressions | Admin API settings | Lineage is incomplete, no measure expressions, no Power Query source parsing. |
A recurring belief, "the read-only admin APIs setting supersedes the Fabric public APIs one", is wrong and regularly produces multi-week stalls. The two settings gate different API families: admin APIs do tenant-wide discovery; Fabric public APIs read report pages, dataset parameters, dataflow definitions, and report definitions. With only admin APIs enabled, discovery works but the catalog is missing pages and lineage. Enable all four.
Microsoft applies tenant-setting and group-membership changes in 15-30 minutes. Preflight checks run immediately, so a "still failing" result within half an hour of a change isn't a signal. Also note: only a Fabric Administrator can see the Tenant settings page, and it's under Tenant settings, not Capacity settings, an easy place to look first by mistake.
Grant workspace access
Add the security group (not the bare service principal) to each workspace you want cataloged. The role decides how much Atlan can see:
| Workspace role | What Atlan can extract |
|---|---|
| Viewer | Dashboards and reports only |
| Contributor | + datasets with parameters, and column and measure lineage to pages |
| Member | + dataflows and full lineage, recommended |
Power BI teams often push back on Member access. The matrix in the previous section is the negotiation tool: agree on what metadata you're willing to lose at each lower rung.
This lineage is built from each report's definition, which Atlan reads with Microsoft's Get Report Definition Fabric API. Microsoft requires that "the caller must have read and write permissions for the report," so a Viewer role fails it even with every tenant setting enabled. Grant the security group Contributor or higher. Microsoft's workspace roles lists what each role can write.
Reports carrying an encrypted sensitivity label are blocked by Microsoft whatever the role, and contribute no lineage.
Scanner API trade-off
Atlan's crawler has an "Enable Scanner APIs Only Access" toggle. It changes the access model entirely:
| Toggle OFF (default, recommended) | Toggle ON (scanner-only) | |
|---|---|---|
| Workspace membership needed | Yes, group added to each workspace | No, reads via tenant admin APIs |
| Report pages | Extracted | Not extracted |
| Measure-level lineage | Full | Degraded |
| Setup effort | Higher (workspace grants) | Lower |
A common trap is enabling scanner mode just to get past a failing preflight, it "works," then weeks later someone asks why pages and measure lineage are missing. Fix the tenant setting instead. Also: in scanner mode, JDBC errors and 403s in logs for workspaces the service principal can't access are expected noise, not failures.
Checklist before moving on
- All four tenant settings enabled, each scoped to the security group
- Security group granted to target workspaces (Member for full lineage)
- Role is Contributor or higher for column and measure lineage to pages
- 30 minutes elapsed since the last settings change
- Decision recorded: scanner-only ON or OFF (default OFF)