Configure Power BI tenant settings
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 (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. 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, and dataflow 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 |
| 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.
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)
- 30 minutes elapsed since the last settings change
- Decision recorded: scanner-only ON or OFF (default OFF)