| name | fabric-core |
| description | Core Microsoft Fabric platform reference: topology, authentication, token scopes, REST API base URL, pagination, long-running operations, throttling, workspace and item resolution, OneLake access, and common gotchas. Use this skill whenever working with Fabric REST APIs, managing workspaces/items, or troubleshooting auth errors.
|
Fabric Core Platform
Topology
| Concept | Description |
|---|
| Tenant | Single Fabric instance per organisation, aligned with one Microsoft Entra ID tenant |
| Capacity | Compute pool (F-SKU or P-SKU) powering Fabric workloads. Every workspace must be assigned to one |
| Workspace | Container for Fabric items. Defines collaboration and security boundary |
| Item | Artefact inside a workspace — Lakehouse, Warehouse, Notebook, SemanticModel, etc. Each has a unique GUID |
| OneLake | Unified tenant-wide data lake. All items store data as Delta/Parquet files in OneLake |
Environment URLs
| Service | URL |
|---|
| Fabric REST API | https://api.fabric.microsoft.com/v1/ |
| OneLake DFS (global) | https://onelake.dfs.fabric.microsoft.com |
| OneLake Blob (global) | https://onelake.blob.fabric.microsoft.com |
| Warehouse / SQL Endpoint TDS | <unique-id>.datawarehouse.fabric.microsoft.com:1433 |
| XMLA Endpoint | powerbi://api.powerbi.com/v1.0/myorg/<workspace> |
| Entra ID Token Endpoint | https://login.microsoftonline.com/<tenantId>/oauth2/v2.0/token |
| Power BI REST API | https://api.powerbi.com/v1.0/myorg/ |
| KQL Cluster URI | https://trd-<hash>.z<n>.kusto.fabric.microsoft.com (per-item) |
Authentication
All Fabric REST API calls require a Microsoft Entra ID OAuth 2.0 bearer token. No API keys, SAS tokens, or SQL auth for REST APIs.
Token Audiences / Scopes
Using the wrong audience is the #1 cause of 401 Unauthorized.
| Access Target | Scope |
|---|
| Fabric REST API | https://api.fabric.microsoft.com/.default |
| Power BI REST API (legacy) | https://analysis.windows.net/powerbi/api/.default |
| OneLake (DFS / Blob) | https://storage.azure.com/.default |
| Warehouse / SQL Endpoint (TDS) | https://database.windows.net/.default |
| KQL / Kusto | https://kusto.kusto.windows.net/.default |
| XMLA Endpoint | https://analysis.windows.net/powerbi/api/.default |
| Azure Resource Management | https://management.azure.com/.default |
OneLake gotcha: Only accepts https://storage.azure.com/.default. Using https://datalake.azure.net/ will fail.
Identity Types
| Identity | Use case |
|---|
| User principal | Interactive human user (broadest API support) |
| Service principal (SPN) | App registration. Requires admin consent + tenant setting |
| Managed identity | Azure-managed. Works from Azure compute |
| Workspace identity | Fabric-managed SPN tied to a workspace. No secret to manage |
Entra App Registration
- Create app registration at
https://entra.microsoft.com
- Add redirect URI
http://localhost for interactive flows
- Add API permissions under Power BI Service:
Workspace.ReadWrite.All, Item.ReadWrite.All, OneLake.ReadWrite.All
- Enable "Service principals can use Fabric APIs" in Fabric Admin Portal
CLI Authentication
az login
az account get-access-token --resource https://api.fabric.microsoft.com
az rest --method get \
--resource "https://api.fabric.microsoft.com" \
--url "https://api.fabric.microsoft.com/v1/workspaces"
Core REST APIs
Base URL: https://api.fabric.microsoft.com/v1
All requests require Authorization: Bearer <token> and Content-Type: application/json for POST/PUT/PATCH.
Workspace Operations
GET /v1/workspaces # List workspaces
GET /v1/workspaces/<workspaceId> # Get workspace
POST /v1/workspaces # Create workspace
{ "displayName": "...", "capacityId": "..." }
POST /v1/workspaces/<id>/assignToCapacity # Assign capacity
{ "capacityId": "..." }
GET /v1/capacities # List available capacities
Item Operations
GET /v1/workspaces/<wsId>/items # List all items
GET /v1/workspaces/<wsId>/items?type=Lakehouse # Filter by type
GET /v1/workspaces/<wsId>/items/<itemId> # Get item
POST /v1/workspaces/<wsId>/items # Create item
{ "displayName": "...", "type": "<ItemType>" }
Type-specific endpoints return additional properties:
GET /v1/workspaces/<wsId>/{lakehouses|warehouses|notebooks|semanticModels|kqlDatabases|...}
Resolve Workspace by Name
az rest --method get \
--resource "https://api.fabric.microsoft.com" \
--url "https://api.fabric.microsoft.com/v1/workspaces" \
--query "value[?displayName=='MyWorkspace'] | [0].id" \
--output tsv
Resolve Item by Name
az rest --method get \
--resource "https://api.fabric.microsoft.com" \
--url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/items?type=Lakehouse" \
--query "value[?displayName=='MyLakehouse'] | [0].id" \
--output tsv
Job Execution
POST /v1/workspaces/<wsId>/items/<itemId>/jobs/instances?jobType=<jobType>
| Item Type | jobType |
|---|
| Notebook | RunNotebook |
| DataPipeline | Pipeline |
| SparkJobDefinition | SparkJob |
| SemanticModel | Refresh |
Gotcha: DefaultJob does NOT work for most item types. Use the type-specific value.
Pagination
All list APIs use continuation-token-based pagination.
- Make the initial
GET request
- If response contains
continuationToken (non-null), repeat with ?continuationToken=<value>
- Continue until
continuationToken is null or absent
Use continuationUri directly if provided. Never modify the token — it is opaque.
Long-Running Operations (LRO)
Many mutating operations return 202 Accepted with:
Location — poll URL
x-ms-operation-id — operation GUID
Retry-After — seconds to wait
Poll: GET /v1/operations/<operationId> → { "status": "Running|Succeeded|Failed" }
Get result: GET /v1/operations/<operationId>/result (after Succeeded)
Best practices: Honour Retry-After. Use exponential backoff if absent. Set a max timeout. Handle Failed gracefully.
Throttling
HTTP 429 Too Many Requests includes Retry-After header. Callers must wait.
| API Category | Limit |
|---|
| Admin APIs | 200 req/hour per principal per tenant |
| General Fabric APIs | Varies by endpoint |
| OneLake ADLS APIs | Standard Azure Storage throttling (per-workspace) |
Implement retry with exponential backoff + jitter. Respect Retry-After. Avoid tight polling loops.
OneLake Data Access
URL Structure
https://onelake.dfs.fabric.microsoft.com/<workspace>/<item>.<itemtype>/<path>
ABFS URI (for Spark):
abfss://<workspace>@onelake.dfs.fabric.microsoft.com/<item>.<itemtype>/<path>
<workspace> — GUID or display name (use GUID for ABFS)
<item>.<itemtype> — e.g. MySalesLakehouse.Lakehouse
<path> — Tables/<tableName> or Files/<folder>/<file>
OneLake only accepts scope = https://storage.azure.com/.default.
Common Errors
| Error | Cause | Fix |
|---|
401 Unauthorized | Wrong token audience or expired token | Verify aud claim. Check scope table above |
403 Forbidden | Missing workspace role or item permission | Check role assignments. For SPNs: verify admin portal settings |
404 Not Found | Wrong workspace/item ID | Re-resolve the workspace/item |
429 Too Many Requests | Rate limit exceeded | Wait for Retry-After, then retry |
FeatureNotAvailable | Workspace has no capacity assigned | Assign capacity first, verify capacityAssignmentProgress is "Completed" |
Best Practices
- Parameterize all URLs — base URL, workspace ID, item ID, token audience
- Use type-specific list endpoints when item properties are needed
- Check before creating — implement idempotent operations
- Wrap all mutating calls in an LRO-aware handler
- Log
x-ms-request-id from responses for support requests
- Cache workspace/item metadata — avoid repeated list calls
- Prefer GUIDs over display names for programmatic access
- Store secrets in Key Vault — never in source code
- Distinguish transient (429/503/504) vs permanent (400/403/404) errors