Connector Setup & Configuration

Architecture

The REFRACT Platform Connector uses a single-tenant, service-to-service architecture. Each organization's Power Platform environment connects directly to its own Dispatcher - there is no shared Refract Logic infrastructure in the data path.

Power Automate Flow
      │
      ▼
REFRACT Platform Connector (Power Platform)
      │  reads 5 connection parameters (Dispatcher URL, Tenant ID,
      │  Client ID, Client Secret, Scope)
      │  connector script acquires a token via
      │  grant_type=client_credentials, then forwards the request
      ▼
Customer-hosted REFRACT Dispatcher (Azure Function App)
      │  validates JWT claims (iss, aud, tid)
      ▼
REFRACT Platform Services
  ├── PDF Generation
  ├── e-Signature Processing
  ├── Approval Workflows
  ├── Audit & Compliance
  └── Document Storage (Blob / SharePoint)

Data sovereignty: OAuth tokens are issued by the customer's own Microsoft Entra ID tenant, using an App Registration the customer's IT admin controls. Documents are generated and stored within the customer's Azure subscription; when a flow triggers REFRACT eSign or REFRACT Workflow, every document download redirects the browser to the customer's own Dispatcher, which streams the bytes directly - the REFRACT-hosted portal never receives them.

Prerequisites

Before creating a connection:

1. REFRACT Platform Dispatcher deployed and running in the customer's Azure subscription
2. Microsoft Entra ID App Registration for the connector to authenticate with, using client credentials (see below)
3. Power Platform environment with System Administrator or Environment Maker permissions

Step 1: Create the App Registration

The connector authenticates to the Dispatcher using OAuth 2.0 client credentials (an app-to-app token, not a per-user sign-in). Each connection stores its own tenant ID, client ID, client secret, and scope, and the connector's own code (a custom connector script) exchanges these for a Bearer token on every call - there is no function key involved.

Step 2: Create a Connection

Once the connector is deployed, it appears in the Power Automate custom connectors list and flow makers can create connections.

Flow makers (or the IT admin, on their behalf) create connections by entering five values. There is no sign-in step.

Open Power Automate

Go to make.powerautomate.com → Data → Connections → + New connection.

Find and Select REFRACT Platform

Search for REFRACT Platform. Select the connector.

Enter the Connection Fields

Parameter	Description	Example
Dispatcher URL	Dispatcher Function App base URL - no /api suffix	https://func-dispatcher-contoso-prod.azurewebsites.net
Azure AD Tenant ID	Organization's Microsoft Entra ID tenant GUID	c49962a1-53d3-4af8-8d5d-35f34cd0be9c
Client ID	Application (client) ID of the App Registration from Step 1	(from Azure Portal)
Client Secret	That App Registration's client secret value	(shown once at creation)
OAuth Scope	Scope for the Dispatcher's App Registration	api://<dispatcher-app-client-id>/.default

Dispatcher URL must not include /api

Enter https://func-dispatcher-contoso-prod.azurewebsites.net - the connector appends /api/ to all request paths automatically. If you include /api in the URL the requests will fail with 404.

Create the Connection

Click Create. There is no sign-in window - this connector uses client credentials, so the connection is saved immediately with the five values above. The connector does not define a connection test, so a wrong value only surfaces as an authentication error on the first flow run that uses this connection.

Connection Parameter Reference

These five values are stored per connection - there is no connector-level OAuth configuration shared across connections. Each connection can use a different App Registration if needed.

Authentication Model

The REFRACT Platform Connector uses OAuth 2.0 client credentials - an app-to-app token, not an interactive user sign-in.

On every action call, the connector's own script (script.csx) reads the connection's tenant ID, client ID, client secret, and scope (injected as request headers by the connection's policy templates, then stripped before forwarding), posts a grant_type=client_credentials request to https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token, and attaches the resulting access token as a Bearer header on the forwarded request to the Dispatcher.

The client secret is stored encrypted as part of the connection. It is used only to acquire tokens from Azure AD - it is never forwarded to the Dispatcher and never visible again after the connection is saved.

JWT Validation

Before processing any request, the Dispatcher validates:

• Issuer (iss) - Token must be issued by the authorised Microsoft Entra ID tenant.
• Audience (aud) - Token must be intended for the Dispatcher's application registration. Both a bare client-ID audience and an api://-prefixed audience are accepted and compared as equal.
• Tenant ID (tid) - Token must belong to the tenant configured in the Dispatcher's AZURE_TENANT_ID setting.

All three validations must succeed. Tokens issued for another tenant or another application are rejected before request processing begins. There is no IP allowlist and no gateway-registration check - a token that passes these three checks must also hold the Render.Access application permission, or it is refused with 403 and code ROLE_MISSING. Nothing checks where the request originates.

Execution Model

Every action call runs through the connector's script.csx: it reads the credential headers, requests a token from Azure AD, attaches it as a Bearer header, and forwards the request to the Dispatcher.

Power Platform's custom-code connectors (the script.csx mechanism) carry a platform-level 5-second CPU budget, but time spent waiting on network calls - the Azure AD token request and the Dispatcher's own processing - does not count against it.

In practice, the effective limit is the Power Automate action timeout (typically 120 seconds). Document generation time varies with template complexity and payload size.

Dispatcher Environment Variables

The Dispatcher Function App must have these environment variables configured:

Multiple Environments

Create a separate connection for each environment (dev, test, prod). Each environment's Dispatcher has its own "REFRACT Dispatcher API" app registration, so the connection's Dispatcher URL and OAuth Scope both differ per environment. One connector app can hold permissions on several of them, but a connector app per environment keeps production credentials out of test flows.

Deployment Checklist

Before going to production:

• App Registration created and client secret noted
• The connection's OAuth Scope is api://<dispatcher-app-client-id>/.default, using the client ID of "REFRACT Dispatcher API" (the Dispatcher's JWT_AUDIENCE already holds that ID; it needs no change for a new connector)
• Dispatcher env vars set: JWT_ISSUER, JWT_AUDIENCE, AZURE_TENANT_ID (JWT_REQUIRED left unset or "true")
• Connection created with all five values (Dispatcher URL, Tenant ID, Client ID, Client Secret, Scope) - there is no connection test, so verify by running a flow
• The connector's App Registration holds the Render.Access application permission, admin-consented (required for every action)
• If flows use Get Document URL, Check Workflow Status, or Download Sealed PDF: the connector's App Registration has the Lifecycle.Reader application permission, admin-consented (see Integrations that use app tokens)
• Generate Document action tested end-to-end with a real template and payload
• Error handling implemented in flows (Configure run after → failed)
• Client secret expiry date calendared for renewal

Troubleshooting

These errors come from the connector's own script.csx, before the request ever reaches the Dispatcher:

These errors come from the Dispatcher itself, once a valid token reaches it:

Every other code the Dispatcher can return, and when a flow may send a request again, is on Error responses and codes.

Next Steps

• Overview & Quick Start - Build your first flow
• API Reference - Complete parameter definitions and response schemas
• Error responses and codes - Every error code the Dispatcher returns, and when to retry
• Trust Center - Security controls and compliance documentation
• Privacy Policy - Data processing and protection
• Terms of Service - Legal terms of use