Skip to main content

Troubleshooting

assertEnabled() throws​

Set oauth.server.enabled (OAUTH_SERVER_ENABLED) to true.

Authorization code exchange fails with a PKCE error​

oauth.server.pkce.requiredByDefault is true by default — public clients must send a codeChallenge/codeChallengeMethod when creating the authorization code and the matching codeVerifier when exchanging it.

Tokens issued before a restart no longer validate​

Ephemeral signing keys (oauth.server.jwks.signing.allowGeneratedFallback) regenerate on every process start unless privateKeyPem/publicKeyPem are pinned. Set fixed PEM keys for any environment where tokens must survive a restart.

Refresh token reuse is rejected​

oauth.server.refreshToken.rotateOnUse invalidates the previous refresh token as soon as a new one is issued — clients must always use the most recently issued refresh token.

Endpoints return 404​

Confirm an HTTP engine (e.g. @quik/http-express) is registered and booted before @quik/oauth-server, and that the effective route matches http.paths.api combined with oauth.server.http.authenticationPrefix/managementPrefix.