Testing with Postman

Call the Dispatcher API from Postman with a testing app registration, either as an app (client credentials) or as a signed-in person (Authorization Code with PKCE).

You can test the Dispatcher from Postman in two ways. Both use a testing app that you register, never "REFRACT Dispatcher API" itself:

As an app (client credentials): no one signs in, and the token carries the testing app's application permissions. This is how a source system calls.
As a person (Authorization Code with PKCE): you sign in, and the token carries the user_impersonation scope and your own roles. This is how REFRACT Lifecycle calls.

See Postman as an app or as a person for how the two tokens differ.

Prerequisites

A deployed Dispatcher, reachable at https://<your-dispatcher>.azurewebsites.net
The client ID of "REFRACT Dispatcher API" (App registrations -> REFRACT Dispatcher API -> Overview), written below as <dispatcher-app-client-id>
A Microsoft Entra role that can register apps and grant admin consent (Application Administrator or Cloud Application Administrator)

Step 1: Register the Testing App

Create it like a connector app

Follow Create a connector app, with a name such as REFRACT API testing. Keep the client ID, tenant ID, and secret value.

Add the permissions for how you will test

Under API permissions -> Add a permission -> APIs my organization uses -> REFRACT Dispatcher API:

To test	Add	Type
As an app	`Render.Access`, and `Lifecycle.Reader` to read document records	Application permissions
As a person	`user_impersonation`	Delegated permissions

Then select Grant admin consent. user_impersonation needs an administrator's consent, so without it the sign-in fails.

Add the Postman redirect URI (as a person only)

Open Authentication -> Add a platform -> Web, and add:

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

Use the Web platform, because Postman sends the testing app's client secret when it exchanges the code. Under Mobile and desktop applications, Microsoft Entra ID treats the app as a public client and refuses the secret.

To read document records as a person, you also need the Lifecycle.Reader role yourself. See Give people access to document records.

Step 2: Configure OAuth 2.0 in Postman

On the request (or collection) you want to test, open the Authorization tab, set Auth Type to OAuth 2.0, and configure a new token.

As an app

Field	Value
Grant Type	Client Credentials
Access Token URL	`https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token`
Client ID	The testing app's client ID
Client Secret	The testing app's secret value
Scope	`api://<dispatcher-app-client-id>/.default`
Client Authentication	Send client credentials in body

As a person

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	The testing app's client ID
Client Secret	The testing app's secret value
Code Challenge Method	SHA-256
Code Verifier	(leave empty - auto-generated)
Scope	`api://<dispatcher-app-client-id>/.default`
Client Authentication	Send client credentials in body

Three easy mistakes

Client ID is the testing app's, not the client ID of "REFRACT Dispatcher API". That ID appears only inside the scope.
Auth URL and Access Token URL are different endpoints: /oauth2/v2.0/authorize and /oauth2/v2.0/token.
"Authorize using browser" must be checked with the oauth.pstmn.io callback. Unchecked, Postman's embedded window fails with Error: [object Object] after a sign-in that looked successful.

Click Get New Access Token. As a person, your system browser opens; sign in with an account from your tenant, and Postman receives the token when the browser returns through the callback.

Step 3: Send the Request

For the core render endpoint:

POST https://<your-dispatcher>.azurewebsites.net/api/render

For a gateway route:

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

Neither route uses a function key. The Dispatcher validates the Microsoft Entra ID token inside the handler, and Postman adds it 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 set to the Auth URL	Confirm the Access Token URL ends in `/oauth2/v2.0/token`
`Error: [object Object]` after a successful-looking sign-in	"Authorize using browser" is unchecked with the `oauth.pstmn.io` callback	Check "Authorize using browser"
`AADSTS90009: Application '<appId>' is requesting a token for itself...`	Client ID is the client ID of "REFRACT Dispatcher API"	Use the testing app's client ID
`AADSTS650057: Invalid resource. The client has requested access to a resource which is not listed in the requested permissions...`	The testing app has no permission on "REFRACT Dispatcher API"	Add the permission from Step 1 and grant admin consent
`AADSTS50011: The redirect URI '...' specified in the request does not match...`	The callback is not registered on the testing app	Add it under Authentication -> Web (Step 1)
`AADSTS700025: Client is public so neither 'client_assertion' nor 'client_secret' should be presented.`	The callback is registered under Mobile and desktop applications	Register it under Web instead
`403` with code `ROLE_MISSING` and `"role": "Render.Access"`	Testing as an app without `Render.Access`	Add the application permission and grant admin consent, then get a new token
`403` with code `ROLE_MISSING` and `"role": "Lifecycle.Reader"`	The route reads document records	As an app: add the `Lifecycle.Reader` application permission. As a person: get the role assigned to you, then sign in again.
`403` with code `SCOPE_MISSING`	Your sign-in token does not carry `user_impersonation`	Add the delegated `user_impersonation` permission to the testing app, grant admin consent, and get a new token
`401 Unauthorized`, `WWW-Authenticate: Bearer error="invalid_token"`	The Dispatcher rejected the token	Confirm the scope names "REFRACT Dispatcher API", the token comes from your tenant, and it has not expired

Next Steps

Connect a source system - Connector apps for each system, and the 403 codes
Authentication - The two flows and who may call
REFRACT Dispatcher API Overview - Endpoint list and the two auth models compared

On this page