REFRACT Dispatcher API
Overview of the customer-hosted REFRACT Dispatcher's HTTP API, its Microsoft Entra ID App Registration, and the two authentication models available to callers.
Every REFRACT Platform deployment exposes its rendering, e-signature, workflow, and delivery capabilities through a single customer-hosted Azure Function App: the Dispatcher. All integrations, whether a Power Automate flow, a Postman test, an ERP connector, or a script, ultimately call this same API.
Single-tenant, self-hosted
There is no shared Refract Logic service in the request path. The Dispatcher runs inside your own Azure subscription, and every access token is issued by your own Microsoft Entra ID tenant.
The "REFRACT Dispatcher API" App Registration
Every Dispatcher deployment provisions one Microsoft Entra ID App Registration, named "REFRACT Dispatcher API" by default (infra/deploy.ps1 creates and configures it automatically as part of Step 6 - Deploy Infrastructure in the customer deployment guide). This app registration is a resource, not a client: it defines the API surface that other applications request tokens for. It is configured with:
| Configuration | Purpose |
|---|---|
Application ID URI (api://<appId>) | Lets Microsoft Entra ID resolve api://<appId> as a token audience |
Render.Access app role | Application permission for service-to-service (client credentials) callers |
user_impersonation delegated scope | Delegated permission for callers that sign in as a user (SPFx, interactive testing) |
| Self-referencing delegated permission, admin-consented | Required whenever this same app is used as both client and resource - see Authentication |
This one app registration has no client secret by default, and does not need one for its primary role as a resource. A secret is only needed when a separate client app authenticates against it, or when this app is itself used as a public client via PKCE.
Two Ways to Call the Dispatcher
Pick the model that matches your caller
Which authentication model you use depends on whether a human is present when the call happens.
| Delegated (Authorization Code + PKCE) | Client Credentials | |
|---|---|---|
| Who signs in | A human, interactively | Nobody - service-to-service |
| Client app | "REFRACT Dispatcher API" itself (self-referencing) | A separate, dedicated App Registration |
| Client secret needed | No | Yes |
| Typical use | SPFx dashboard, Postman / manual API testing | Power Platform connector, ERP integrations (Business Central, Dynamics), scripts, scheduled jobs |
| Where it's documented | Authentication, Testing with Postman | Power Platform Connector Setup |
Business Central, Dynamics 365 Sales, and Dynamics GP
REFRACT Platform already integrates with Microsoft Dynamics 365 Business Central, Dynamics 365 Sales, and Dynamics GP using this same client-credentials pattern - each via its own dedicated App Registration granted the Render.Access application permission against "REFRACT Dispatcher API". See the Business Central and Dynamics 365 Sales integration guides for the product-specific setup. Any further ERP integration follows the identical pattern: a dedicated App Registration, Render.Access granted and admin-consented, authenticating with grant_type=client_credentials.
Endpoints
| Endpoint | Auth level | Auth model | Notes |
|---|---|---|---|
POST /api/render | Function key + optional JWT | Either, when JWT_REQUIRED=true | The core render endpoint. Also used for REFRACT Dispatch batch submission. |
POST /api/gateway/v1/documents/generate | JWT only (no function key) | Either | Gateway route used by the Power Platform connector and suitable for any pure-OAuth integration. |
GET /api/gateway/v1/documents/open | JWT only | Either | Returns a short-lived signed download URL. |
GET /api/gateway/v1/workflows/{workflowId} | JWT only | Either | Poll workflow/signature status. |
GET /api/gateway/v1/workflows/{workflowId}/pdf | JWT only | Either | Retrieve the sealed PDF once complete. |
GET/POST /api/dispatch/batch/* | JWT only | Either | REFRACT Dispatch batch lifecycle management - see REFRACT Dispatch API Reference. |
Every request, regardless of endpoint or auth model, is validated against the same three JWT claims:
| Claim | Validates |
|---|---|
aud | Token was issued for this Dispatcher's App Registration |
iss | Token was issued by this tenant's own Microsoft Entra ID |
tid | Token belongs to the authorised tenant |
Next Steps
- Authentication - The two auth models in detail, and the App Registration gotchas that trip up self-referencing delegated tokens
- Testing with Postman - Step-by-step OAuth 2.0 configuration for manual API testing
- Power Platform Connector Setup - Client-credentials setup for Power Automate and Power Apps
- REFRACT Dispatch API Reference - Batch dispatch lifecycle endpoints
API Reference
Complete parameter definitions, response schemas, feature flags, and error codes for all four REFRACT Platform Power Platform connector actions.
Authentication
How the Dispatcher's App Registration supports both delegated and client-credentials authentication, and the Microsoft Entra ID gotchas specific to the self-referencing delegated pattern.