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 change the token endpoint path or the auth collection, 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 collection. Without it, it uses 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)
expires_in is the number of seconds until the token expires. 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. Every secured operation lists both PayloadToken and PayloadLogin, so the UI sends the token with either one.
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, and the spec does not list the PayloadLogin scheme — see Static spec.