Dataverse Skill

Agent Summary

Use this skill for Dataverse Web API requests when an agent needs direct OData access instead of PAC CLI abstractions. The token audience is the Dataverse environment URL itself, so start by creating a context with Connect-DataverseApi.ps1.

When to Use

• Query Dataverse tables with OData filters, selects, and pagination.
• Connect to a known Dataverse environment or discover one through the Global Discovery Service.
• Perform direct CRUD operations against Dataverse entities.

Required Parameters

Connect-DataverseApi.ps1

Invoke-DataverseRequest.ps1

Example Agent Prompts

• "List the first 50 Dataverse accounts with accountid and name."
• "Query Dataverse contacts where emailaddress1 is not null."
• "Patch a Dataverse account record by ID."

Example Agent Workflow

$ctx = ./skills/dataverse/Connect-DataverseApi.ps1 -AuthenticationType ManagedIdentity -Environment AzureCloud -EnvironmentUrl $env:DATAVERSE_ENVIRONMENT_URL

$accounts = ./skills/dataverse/Invoke-DataverseRequest.ps1 -AuthContext $ctx -Uri "/accounts?`$select=accountid,name&`$top=50" -Paginate

Security Caveats

• The Dataverse environment URL is the token audience; do not substitute Graph or ARM tokens.
• Prefer managed identity or federated credentials over client secrets.
• Grant only the Dataverse roles and table permissions required for the requested entity operations.

Overview

This skillset connects to Microsoft Dataverse Web API and executes OData requests with consistent auth, environment discovery, and retry behavior.

Authentication

• Auth types: ManagedIdentity, Federated, Certificate, ClientCredentials (emits a mandatory warning when using client secrets).
• Token audience is the environment URL itself (not Graph or ARM). The environment root URL is used as the OAuth resource, so the token is scoped with $Resource/.default.
• Global Discovery Service for environment lookup to translate an environment URL into the correct Web API base URI.

Endpoints

Skills

Toolchain

Patterns & Caveats

• OData query syntax
• File uploads/downloads need special handling
• Pagination
• Environment URL as token audience

Examples

# 1) GDS lookup, then run an OData query with pagination
$authToken = $env:AZURE_FEDERATED_TOKEN

$environments = Get-DataverseEnvironment.ps1 \
  -AuthenticationType Federated \
  -TenantId $env:TENANT_ID \
  -ClientId $env:CLIENT_ID \
  -FederatedToken $authToken \
  -Environment AzureCloud

$target = $environments | Where-Object { $_.UniqueName -eq 'contoso' } | Select-Object -First 1

$ctx = Connect-DataverseApi.ps1 \
  -AuthenticationType Federated \
  -TenantId $env:TENANT_ID \
  -ClientId $env:CLIENT_ID \
  -FederatedToken $authToken \
  -Environment AzureCloud \
  -EnvironmentUrl $target.url

$accounts = Invoke-DataverseRequest.ps1 \
  -AuthContext $ctx \
  -Uri "/accounts?`$select=accountid,name&`$top=5000" \
  -Paginate

# 2) Certificate-based auth and a filtered OData query
$ctx = Connect-DataverseApi.ps1 \
  -AuthenticationType Certificate \
  -TenantId $env:TENANT_ID \
  -ClientId $env:CLIENT_ID \
  -CertificatePath "/secure/certs/app.pfx" \
  -Environment AzureCloud \
  -EnvironmentUrl $env:DATAVERSE_ENVIRONMENT_URL

$contacts = Invoke-DataverseRequest.ps1 \
  -AuthContext $ctx \
  -Uri "/contacts?`$select=contactid,fullname,emailaddress1&`$filter=emailaddress1 ne null" \
  -Paginate

# 3) Patch a record using the Dataverse Web API
$ctx = Connect-DataverseApi.ps1 \
  -AuthenticationType ManagedIdentity \
  -Environment AzureCloud \
  -EnvironmentUrl $env:DATAVERSE_ENVIRONMENT_URL

$accountId = "00000000-0000-0000-0000-000000000001"

Invoke-DataverseRequest.ps1 \
  -AuthContext $ctx \
  -Method PATCH \
  -Uri "/accounts($accountId)" \
  -Body @{ name = 'Contoso Updated Account' }

Prerequisites

• Required modules: PowerShell 7.2+; Az.Accounts, Az.Resources, and Azure modules installed via prerequisites/Install-RequiredModules.ps1 (MSAL.PS optional for certificate validation).
• Required permissions: An Entra ID app registration with Dataverse Web API access for the specific Dataverse environment (the token audience is the environment URL), plus Dataverse security roles that permit the entity reads and writes you will perform.

Related Docs

• Auth Patterns
• Token Chaining
• Environment Endpoints