`getAccessTokenSilently` is typed `Promise<string>` but can resolve `undefined`

[catnipan]

Checklist

• The issue can be reproduced in the auth0-react sample app (or N/A).
• I have looked into the Readme, Examples, and FAQ and have not found a suitable solution or answer.
• I have looked into the API documentation and have not found a suitable solution or answer.
• I have searched the issues and have not found a suitable solution or answer.
• I have searched the Auth0 Community forums and have not found a suitable solution or answer.
• I agree to the terms within the Auth0 Code of Conduct.

Description

getAccessTokenSilently is typed as returning Promise<string> (src/auth0-context.tsx#L67), but at runtime it can resolve to undefined. TypeScript users therefore get no prompt to handle the undefined case, and the typical failure is a silent Authorization: Bearer undefined header sent to an API.

The undefined originates in auth0-spa-js's getTokenSilently, which auth0-react wraps and returns verbatim (the wrapper does token = await client.getTokenSilently(opts); … return token; with no guard). There are two runtime paths that produce undefined:

1. cacheMode: 'cache-only' with a cache miss — src/Auth0Client.ts#L998:

   if (cacheMode === 'cache-only') {
     return;                      // bare return → undefined
   }

2. Session ceiling reached — src/Auth0Client.ts#L979:

   if (await this._isSessionCeilingReached()) {
     return undefined;
   }

   Notably this fires on a plain getAccessTokenSilently() call with default options (when the cached ID token carries a session_expiry claim that has passed). It also clears the local session as a side effect and then resolves undefined rather than throwing — so callers get neither a token nor an exception.

The SDK's internals already acknowledge this: the private _getTokenSilently is typed Promise<undefined | GetTokenSilentlyVerboseResponse> and the public wrapper reads result?.access_token with optional chaining (src/Auth0Client.ts#L969) — the undefined is known, it's just erased at the public type boundary (src/Auth0Client.ts#L910, mirrored in auth0-react's Auth0ContextInterface).

Expected: the public return type should tell the truth — Promise<string | undefined> (or, if preferred, a narrowed overload so only cacheMode: 'cache-only' widens to string | undefined, with the session-ceiling path either included or changed to throw). Whatever shape is chosen in auth0-spa-js, auth0-react's re-declared getAccessTokenSilently type needs the same fix.

auth0-react version

2.22.1 (with @auth0/auth0-spa-js 2.24.1)

React version

19.2

Which browsers have you tested in?

Chrome

[yogeshchoudhary147]

Thanks for the detailed report! You're right, the return type should reflect string | undefined for the cacheMode: 'cache-only' and session-ceiling paths. The root fix needs to land in auth0-spa-js first, but we'll align the types here once that's done.