Skill: Custom Connectors
When to Use
Trigger when building, configuring, or debugging custom connectors — reusable API wrappers that expose REST APIs as Power Platform connectors for use in Power Automate, Power Apps, and Copilot Studio.
When to Use Custom Connectors vs Alternatives
| Scenario | Use | Why |
|---|---|---|
| Standard connector exists | Standard connector | Zero maintenance, Microsoft-supported |
| REST API used in one flow only | HTTP action in Power Automate | Simpler, no connector overhead |
| REST API used across multiple flows/apps | Custom connector | Reusable, typed, discoverable |
| REST API with complex auth (OAuth 2.0) | Custom connector | Auth handled once, shared across all uses |
| High-volume API calls needing throttling | Custom connector + Azure APIM | APIM handles rate limiting, caching, monitoring |
| On-premises API (no public endpoint) | Custom connector + On-premises Data Gateway | Gateway bridges private network |
Project Structure
custom-connectors/ contoso-erp/ apiDefinition.swagger.json # OpenAPI 2.0 definition apiProperties.json # Connector metadata + policies icon.png # 160x160 connector icon settings.json # Test settings README.md
⚠️ REQUIRED: Load Sub-Files Before Implementation
SKILL.md is a summary only — it is NOT sufficient for implementation.
The detailed content (complete payloads, XML templates, working examples, edge-case handling) lives in sub-files in the same directory as this SKILL.md. Before writing any code, you MUST use read_file on the sub-files relevant to your task:
- OpenAPI Definition — Swagger structure, action definitions, schema definitions, x-ms extensions, dynamic values/schema
- Authentication — API Key, OAuth 2.0 (Authorization Code), Azure AD / Entra ID, apiProperties.json configuration
- Triggers — Polling triggers (batch), webhook triggers, deregistration endpoint, trigger hints
- Policies & APIM — Connector policies (set header, route request), Azure APIM integration, DLP classification, CLI workflow, solution-aware connectors
Best Practices
- Always use
x-ms-summaryon every parameter and property (maker-friendly display names) - Always set
x-ms-visibility: "internal"for technical parameters users shouldn't see - Always define response schemas (Power Automate needs them for dynamic content)
- Use
x-ms-dynamic-valuesfor dropdown parameters (don't force users to type GUIDs) - Test with both Power Automate and Canvas App (behaviour can differ)
- Version your connector:
host+basePathshould include version (e.g.,/v2/) - Icon must be exactly 160x160px PNG with brand colour background
Anti-Patterns
- Missing
x-ms-summaryon parameters (users see raw field names) - Missing response schemas (dynamic content unavailable in flow designer)
- Using
x-ms-visibility: "internal"on required user inputs (hides needed fields) - Hardcoded hostnames in OpenAPI definition (use connection parameter for environment switching)
- Not classifying connector in DLP policy (blocks use with Dataverse/SharePoint)
- Polling triggers without proper 202 handling (triggers fire with empty data)
- Not including connector in solution (breaks ALM)
- Using Basic auth for production connectors (use OAuth 2.0 or API key)
- Missing error response definitions (poor error handling in flows)
Related Skills
power-automate— Flows consume custom connectors as actions and triggerscode-apps— Code Apps can use connectors viapac code add-data-source -cdataverse-web-api— Alternative when data lives in Dataverse (no connector needed)alm— Solution packaging and deployment of custom connectors


