README

A comprehensive Laravel package for interacting with the Microsoft Power BI REST API. Built on Saloon v4 with type-safe responses, automatic caching, and multiple OAuth2 authentication flows.

Features

• Multiple Authentication Flows: Service Principal, Admin Service Principal, and Azure User (authorization code)
• Type-Safe DTOs: Immutable response objects with full IDE autocomplete
• Automatic Caching: Configurable response caching via Saloon's cache plugin
• Account Type Restrictions: Automatic enforcement of API access restrictions
• Pagination Support: Automatic handling of continuation tokens
• Comprehensive API Coverage: Groups, Reports, Dashboards, Embed Tokens, and Admin endpoints

Requirements

• PHP 8.1+
• Laravel 9.x, 10.x, 11.x, or 12.x
• Microsoft Power BI Pro or Premium account
• Azure AD application with Power BI API permissions

Installation

composer require interworks/laravel-powerbi

Publish the configuration file:

php artisan vendor:publish --tag="laravel-powerbi-config"

Add your Power BI credentials to your .env file:

# Azure AD Configuration
POWER_BI_TENANT=your-tenant-id

# Cloud Environment (Optional)
# One of: commercial (default), gcc, gcc_high, dod
POWER_BI_CLOUD_ENVIRONMENT=commercial

# Service Principal (Client Credentials)
POWER_BI_CLIENT_ID=your-client-id
POWER_BI_CLIENT_SECRET=your-client-secret

# Admin Service Principal (Optional)
POWER_BI_ADMIN_CLIENT_ID=your-admin-client-id
POWER_BI_ADMIN_CLIENT_SECRET=your-admin-client-secret

# Azure User OAuth Redirect (Optional)
POWER_BI_REDIRECT_URI=https://your-app.com/auth/powerbi/callback

# Caching Configuration
POWER_BI_CACHE_ENABLED=true
POWER_BI_CACHE_EXPIRY_SECONDS=3600

US Government Sovereign Clouds (GCC, GCC High, DoD)

Power BI tenants on Microsoft US Government licenses use different REST API and authentication endpoints than the commercial cloud. Set POWER_BI_CLOUD_ENVIRONMENT (or pass cloudEnvironment to any factory method / connector) to route requests to the correct endpoints:

GCC authority: GCC (moderate) identities live in commercial Microsoft Entra, so gcc authenticates against login.microsoftonline.com (same as commercial) while still using the powerbigov.us API host and usgovcloudapi.net resource. Only GCC High and DoD use the Azure Government authority login.microsoftonline.us.

// Explicit per-connector override
$connector = PowerBI::servicePrincipal(
    tenant: 'your-tenant-id',
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
    cloudEnvironment: 'gcc'
);

A missing or empty value defaults to commercial. Any other unrecognized value (e.g. a typo like gcc-high) throws an InvalidArgumentException when the connector is created, so a sovereign-cloud tenant can never be silently routed to the commercial endpoints.

Note: When using the Azure User flow with explicit OAuth scopes, make sure your scope strings reference the resource URL for your cloud environment (see the table above) rather than the commercial analysis.windows.net/powerbi/api resource.

Quick Start

use InterWorks\PowerBI\Facades\PowerBI;

// Authenticate
$token = PowerBI::getAccessToken();
PowerBI::authenticate($token);

// Get groups and reports
$groups = PowerBI::getGroups();
$reports = PowerBI::getReportsInGroup('group-id');
$report = PowerBI::getReportInGroup('group-id', 'report-id');

// Generate embed token
use InterWorks\PowerBI\Requests\EmbedToken\ReportsGenerateTokenInGroup;

$embedToken = PowerBI::send(new ReportsGenerateTokenInGroup(
    groupId: 'group-id',
    reportId: 'report-id',
    accessLevel: 'View'
));

Authentication

The package supports three authentication flows:

Service Principal (Client Credentials)

Best for backend automation and server-to-server communication.

$token = PowerBI::getAccessToken();
PowerBI::authenticate($token);

Restriction: Cannot access individual resource endpoints (/reports/{id}). Use group-scoped endpoints.

Admin Service Principal

For tenant-wide administration with elevated permissions.

$adminConnector = PowerBI::adminServicePrincipal();
PowerBI::setConnector($adminConnector);

Azure User (Authorization Code)

For user-delegated permissions with browser-based consent.

$connector = PowerBI::azureUser(redirectUri: 'https://your-app.com/callback');
$authUrl = $connector->getAuthorizationUrl();
// Redirect user, then exchange code for token

Available Endpoints

The package provides request classes for Power BI API endpoints:

Groups: GetGroups, GetGroupsAsAdmin

Reports: GetReportsInGroup, GetReportInGroup, GetReport

Dashboards: GetDashboardsInGroup, GetDashboardInGroup

Embed Tokens: ReportsGenerateTokenInGroup, DashboardsGenerateTokenInGroup

Admin: GetUserArtifactAccessAsAdmin

Browse all available requests in src/Requests.

Response DTOs

All responses are transformed into type-safe DTOs with readonly properties:

Collections: Groups, Reports, Dashboards, ArtifactAccessResponse

Resources: Group, Report, Dashboard, EmbedToken, ArtifactAccessEntry

$groups = PowerBI::getGroups();

// Laravel Collections with full IDE support
$groups->groups->each(function ($group) {
    echo $group->name; // Fully typed properties
});

Caching

Responses are automatically cached using Laravel's cache system:

POWER_BI_CACHE_ENABLED=true
POWER_BI_CACHE_EXPIRY_SECONDS=3600

Check cache status:

if ($groups->response()->isCached()) {
    // Response served from cache
}

Account Type Restrictions

Power BI API enforces different access levels by authentication type:

Restrictions are enforced automatically with clear exceptions.

Troubleshooting

Authentication failures: Verify Azure AD credentials and Power BI API permissions in your app registration.

Account type restrictions: Service Principal cannot access individual resource endpoints - use group-scoped endpoints or switch to Azure User.

Admin endpoint 401s: Ensure Service Principal has Power BI Administrator role assigned.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for development setup and guidelines.

Changelog

Please see CHANGELOG.md for release history.

Security

Please review our security policy on how to report security vulnerabilities.

Credits

• mrkbingham
• All Contributors

Built with Saloon v4.

License

The MIT License (MIT). Please see License File for more information.