From 1d62f0affd3efea7a6a9610bf1e53063347192e4 Mon Sep 17 00:00:00 2001 From: Andy Dixon Date: Thu, 26 Feb 2026 13:34:42 +0000 Subject: [PATCH] docs: document refresh invalid_grant on scope tightening Adds integration guidance that refresh-token exchange may fail after provider-side client scope policy is narrowed. --- README.md | 1 + docs/INTEGRATION_GUIDE.md | 1 + 2 files changed, 2 insertions(+) diff --git a/README.md b/README.md index 42658f4..03c1a9b 100644 --- a/README.md +++ b/README.md @@ -146,6 +146,7 @@ This wrapper now delegates to `BlackWall\Auth\AuthClient`. - Never place client secrets, refresh tokens, or access tokens in URL query strings. - For OIDC providers, include a per-request `nonce` in authorisation requests. - Ensure requested `scope` values in SDK config/examples (for example `offline_access`) are enabled on the provider-side client before rollout. +- Expect refresh-token exchange to fail (`invalid_grant`) if provider-side client scopes were tightened and the refresh token now carries disallowed scopes. - For direct Cryptbin API usage, send `key_b64url` on unwrap calls; provider rejects key-mismatch unwrap attempts with `403 Forbidden`. - For newly created Cryptbin items, continue using the creating WebAuthn credential for unwrap/update/delete flows. - Always use HTTPS in production. diff --git a/docs/INTEGRATION_GUIDE.md b/docs/INTEGRATION_GUIDE.md index d8bc240..2771ca7 100644 --- a/docs/INTEGRATION_GUIDE.md +++ b/docs/INTEGRATION_GUIDE.md @@ -139,6 +139,7 @@ try { `TokenExchangeException` with `invalid_grant` can also occur when provider-side client/user/project state is inactive at exchange time. Token introspection can return `active=false` when the token subject (user/project) or client has since been disabled. Provider JWT access tokens are now revocation-aware at `userinfo`; revoked JWTs can fail before natural expiry. +Refresh-token exchange can return `invalid_grant` when provider client scope policy has been tightened and stored refresh scopes are no longer allowed. Provider login/authorization steps can also fail with `access_denied` when account status is disabled before completion. WebAuthn-based login verification can return credential-style failures for disabled accounts even when authenticator assertions are otherwise valid. Existing authenticated sessions may also be invalidated when account status changes to disabled.