fabric-core

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

Environment URLs

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.

OneLake gotcha: Only accepts https://storage.azure.com/.default. Using https://datalake.azure.net/ will fail.

Identity Types

Entra App Registration

1. Create app registration at https://entra.microsoft.com
2. Add redirect URI http://localhost for interactive flows
3. Add API permissions under Power BI Service: Workspace.ReadWrite.All, Item.ReadWrite.All, OneLake.ReadWrite.All
4. Enable "Service principals can use Fabric APIs" in Fabric Admin Portal

CLI Authentication

# Interactive login
az login

# Fabric REST API token
az account get-access-token --resource https://api.fabric.microsoft.com

# Using az rest (must specify --resource for Fabric)
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>

Gotcha: DefaultJob does NOT work for most item types. Use the type-specific value.

Pagination

All list APIs use continuation-token-based pagination.

1. Make the initial GET request
2. If response contains continuationToken (non-null), repeat with ?continuationToken=<value>
3. 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.

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

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