Testing with Postman

Step-by-step Postman OAuth 2.0 configuration for manually testing the Dispatcher API using the delegated Authorization Code + PKCE flow.

This walkthrough configures Postman to call the Dispatcher using the delegated pattern described in Authentication - "REFRACT Dispatcher API" acting as both client and resource, with an interactive sign-in and no client secret.

Prerequisites

A deployed Dispatcher, reachable at https://<your-dispatcher>.azurewebsites.net
Access to the "REFRACT Dispatcher API" App Registration in Azure Portal
A function key for /api/render if testing that endpoint directly (not needed for the /api/gateway/v1/* routes)

Step 1: Register the Postman Redirect URI

Add the redirect URI

Azure Portal -> App registrations -> "REFRACT Dispatcher API" -> Authentication -> Add a platform -> Mobile and desktop applications -> add:

https://oauth.pstmn.io/v1/callback

This must go under "Mobile and desktop applications", not "Web" - see Authentication for why.

Confirm the self-referencing permission is consented

App permissions -> API permissions should show "REFRACT Dispatcher API" listed under Configured permissions with user_impersonation (Delegated), status Granted. infra/deploy.ps1 provisions this automatically; if it's missing, see Authentication for the manual steps.

Step 2: Configure OAuth 2.0 in Postman

On the request you want to test, open the Authorization tab, set Auth Type to OAuth 2.0, and configure a new token with these values:

Field	Value
Grant Type	Authorization Code (With PKCE)
Callback URL	`https://oauth.pstmn.io/v1/callback`
Authorize using browser	Checked
Auth URL	`https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize`
Access Token URL	`https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token`
Client ID	`<dispatcher-app-client-id>`
Client Secret	(leave empty)
Code Challenge Method	SHA-256
Code Verifier	(leave empty - auto-generated)
Scope	`<dispatcher-app-client-id>/.default`
Client Authentication	Send client credentials in body

Two easy mistakes

Auth URL and Access Token URL are different endpoints - /oauth2/v2.0/authorize and /oauth2/v2.0/token respectively. Double-check the suffix if they look identical at a glance.
Scope is the bare GUID, not api://<dispatcher-app-client-id>/.default - see Authentication for why this specific self-referencing case differs from the client-credentials pattern.

Click Get New Access Token. Your system browser opens; sign in with an account from the tenant and accept the consent prompt. Postman receives the token automatically once the browser redirects back through the relay.

Step 3: Send the Request

For the core render endpoint (function-key protected, with JWT enforced on top when JWT_REQUIRED=true):

POST https://<your-dispatcher>.azurewebsites.net/api/render?code=<function-key>

For a pure-OAuth gateway route (no function key needed):

POST https://<your-dispatcher>.azurewebsites.net/api/gateway/v1/documents/generate

Either way, the OAuth 2.0 authorization configured in Step 2 is applied automatically to the request headers.

Troubleshooting

Error	Cause	Fix
`AADSTS900561: The endpoint only accepts POST, OPTIONS requests. Received a GET request.`	Access Token URL is empty, wrong, or accidentally set to the Auth URL	Confirm Access Token URL ends in `/oauth2/v2.0/token`, not `/oauth2/v2.0/authorize`
`Error: [object Object]` after a successful-looking sign-in	"Authorize using browser" is unchecked while using a hosted relay redirect URI (`oauth.pstmn.io`)	Check "Authorize using browser"
`AADSTS90009: Application '<appId>' is requesting a token for itself...`	Scope uses the `api://` App ID URI form instead of the bare GUID	Change Scope to `<dispatcher-app-client-id>/.default` (no `api://` prefix)
`AADSTS650057: Invalid resource. ... List of valid resources from app registration: .`	The app has no self-referencing delegated permission requested/consented	Add the self-referencing `user_impersonation` permission and grant admin consent - see Authentication
`AADSTS50011: The redirect URI '...' specified in the request does not match the redirect URIs configured for the application.`	The redirect URI used in Postman isn't registered on the App Registration yet	Add it under Authentication -> Mobile and desktop applications (Step 1 above)
`401 Unauthorized`, `WWW-Authenticate: Bearer error="invalid_token"`	Token obtained, but rejected by the Dispatcher itself	Confirm `JWT_AUDIENCE`, `JWT_ISSUER`, and `AZURE_TENANT_ID` app settings match the App Registration and tenant used to obtain the token

Next Steps

Authentication - Full explanation of the delegated pattern and its Microsoft Entra ID gotchas
REFRACT Dispatcher API Overview - Endpoint list and the two auth models compared