Custom Connectors: OpenAPI & Authentication

Connecting to the outside world

The OpenAPI definition

An OpenAPI (Swagger) definition is a JSON or YAML file that describes your API:

{
  "swagger": "2.0",
  "info": {
    "title": "LogiFlow Tracking API",
    "version": "1.0",
    "description": "Track shipments and get delivery estimates"
  },
  "host": "api.logiflow.com",
  "basePath": "/v2",
  "schemes": ["https"],
  "paths": {
    "/shipments/{id}": {
      "get": {
        "summary": "Get shipment details",
        "operationId": "GetShipment",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "Shipment details",
            "schema": {
              "type": "object",
              "properties": {
                "id": { "type": "string" },
                "status": { "type": "string" },
                "estimatedDelivery": { "type": "string", "format": "date-time" }
              }
            }
          }
        }
      }
    }
  }
}

Key OpenAPI elements for Power Platform

Element	What It Becomes	Notes
paths	Connector actions and triggers	Each path + HTTP method = one action
operationId	Action name in Power Automate/Power Apps	Must be unique and descriptive
parameters	Input fields in the designer	in: query, in: path, in: header, in: body
responses.200.schema	Output fields available in the designer	Dynamic content picks these up
x-ms-trigger	Marks an operation as a trigger (for Power Automate)	"x-ms-trigger": "single" for webhook triggers

Authentication types

OAuth 2.0 is the most common exam topic — know the flow

Auth Type	How It Works	Best For	User Experience
OAuth 2.0	User signs in to the API provider via authorization code flow; token is managed automatically	APIs with user-specific access (Microsoft Graph, Salesforce, etc.)	User sees a sign-in popup, then connection works automatically
API Key	A static key sent in header or query parameter	Internal APIs, simple services, no per-user access needed	User enters the key once when creating the connection
Basic Auth	Username + password sent with every request	Legacy APIs, simple internal services	User enters username/password when creating connection
No Auth	No credentials — public API	Open/public APIs only	Connection creates instantly — no prompts

OAuth 2.0 configuration

For OAuth, you need:

1. Client ID — identifies your connector to the auth provider
2. Client Secret — proves your connector’s identity
3. Authorization URL — where the user signs in
4. Token URL — where the connector exchanges the auth code for a token
5. Refresh URL — where the connector gets a new token when the old one expires
6. Scope — what permissions the connector requests

💡 Scenario: Marcus configures OAuth for a shipping API

Marcus builds a custom connector for NovaSoft’s Shipping Partner API. The API uses OAuth 2.0:

• Client ID: Registered in the partner’s developer portal
• Client Secret: Stored securely (never in source control)
• Auth URL: https://auth.shippingpartner.com/authorize
• Token URL: https://auth.shippingpartner.com/token
• Scope: shipments.read shipments.write

When a user creates a connection, they see the partner’s sign-in page, authenticate, and grant permissions. The connector handles token refresh automatically.

Importing definitions

You do not always need to write OpenAPI definitions from scratch:

Import Source	How	When to Use
OpenAPI file	Upload a .json or .yaml file	When the API provider gives you a Swagger file
URL	Paste the OpenAPI endpoint URL	When the API serves its own specification
Azure service	Select from Azure API Management or Functions	When your API is hosted in Azure
GitHub	Import from a public GitHub repository	When the API spec is published on GitHub
Postman collection	Import a .postman_collection.json	When you have a Postman collection but no OpenAPI spec

💡 Exam tip: Azure API Management import

If the exam describes an API hosted behind Azure API Management, the correct approach is to import from Azure APIM directly. This auto-generates the OpenAPI definition, configures authentication policies, and sets up the connector with minimal manual work. Do not write the OpenAPI file from scratch when APIM already has the definition.

Question

What is an OpenAPI (Swagger) definition?

Click or press Enter to reveal answer

Answer

A JSON or YAML file that describes a REST API: available endpoints, HTTP methods, parameters, request/response schemas, and authentication. Power Platform custom connectors use OpenAPI 2.0 (Swagger) format to understand the API structure.

Click to flip back

Question

What is the operationId in an OpenAPI definition?

Click or press Enter to reveal answer

Answer

A unique identifier for each API operation. In Power Platform, the operationId becomes the action name in Power Automate and Power Apps. It should be descriptive (e.g., 'GetShipmentById', 'CreateOrder') because makers see it when building flows and apps.

Click to flip back

Question

How does OAuth 2.0 authentication work for custom connectors?

Click or press Enter to reveal answer

Answer

When a user creates a connection: (1) they are redirected to the auth provider's sign-in page, (2) they authenticate and grant permissions, (3) the provider returns an authorization code, (4) the connector exchanges it for an access token, (5) the token is stored and refreshed automatically. The user only signs in once.

Click to flip back

Knowledge Check

Marcus needs to create a custom connector for an API that requires each user to authenticate with their own credentials. The API supports OAuth 2.0 and API key authentication. Which should Marcus configure for the connector?

AAPI key — simpler to configure and works for all usersBOAuth 2.0 — each user authenticates with their own identity, matching the per-user requirementCBasic authentication — username and password per userDNo authentication — handle auth inside each flow

Check Answer

Next up: Custom Connectors: Azure, Policies & Code — advanced connector patterns with Azure Functions, policy templates, and code transforms.