Skip to main content
By default the docs UI expects you to paste a bearer token. Turn on interactiveAuth to add a token endpoint (/api/openapi-auth) plus a matching security scheme, so Scalar and Swagger UI show an Authorize dialog where users log in with their Payload credentials:
payload.config.ts
To mount the token endpoint at a custom path, pass an object. The path is relative to the Payload API route (routes.api, /api by default):
payload.config.ts

​
How the login works

The endpoint logs in against your first auth-enabled collection, falling back to users if none is found. It accepts the username as either email or username, matching how your auth collection is configured — the same value is passed as both, and Payload uses whichever login field the collection defines.

​
Request and response

The token endpoint accepts a POST with form data (username and password fields) and returns the Payload JWT:
Request
Response (200)
On a failed login the endpoint returns 400 with:
Response (400)
The docs UI wires this up for you — users type credentials into the Authorize dialog, the UI exchanges them at the token endpoint, and the returned JWT is attached to every “try it” request.
The interactive auth endpoint exchanges credentials for a live JWT. Only enable it on docs real users are meant to authenticate against, and serve them over HTTPS.
With serve: false the interactive-auth endpoint is not mounted, along with the spec endpoint — see Static spec.