Install AI Tools

B2C Commerce tools, documentation, and skills for your assistant.

Claude

Install the plugin Recommended

bash
claude plugin marketplace add SalesforceCommerceCloud/b2c-developer-tooling
claude plugin install b2c-dx-mcp@b2c-developer-tooling

Start a new Claude Code session. To install for the current project only, run it from your project directory with --scope project.

Manual MCP setup
bash
claude mcp add --transport stdio --scope user b2c-dx-mcp -- npx -y @salesforce/b2c-dx-mcp@latest

Start a new session. To configure the current project only, run it from your project directory with --scope project. See Claude Code MCP setup.

Claude Desktop setup

Codex

Install the plugin Recommended

bash
codex plugin marketplace add SalesforceCommerceCloud/b2c-developer-tooling
codex plugin add b2c-dx-mcp@b2c-developer-tooling

Start a new Codex session in your project. This setup also works with the Codex IDE extension and the ChatGPT Work desktop app.

Manual MCP setup
bash
codex mcp add b2c-dx-mcp -- npx -y @salesforce/b2c-dx-mcp@latest

Or add this to ~/.codex/config.toml (or $CODEX_HOME/config.toml if customized):

toml
[mcp_servers.b2c-dx-mcp]
command = "npx"
args = ["-y", "@salesforce/b2c-dx-mcp@latest"]

Start a new session. See Codex MCP configuration.

ChatGPT online setup

VS Code

Install the plugin Recommended

  1. Open the Command Palette (Cmd/Ctrl+Shift+P) and run Chat: Install Plugin from Source.
  2. Enter SalesforceCommerceCloud/b2c-developer-tooling.
  3. Select b2c-dx-mcp and follow the installation prompts.
  4. Start a new chat in GitHub Copilot.
Manual MCP setup

Add this to .vscode/mcp.json in your workspace:

json
{
  "servers": {
    "b2c-dx-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@salesforce/b2c-dx-mcp@latest"]
    }
  }
}

See VS Code MCP setup.

Copilot CLI setup

Cursor

Reload the MCP server in Cursor after installation.

Manual MCP setup

Add this to .cursor/mcp.json in your project:

json
{
  "mcpServers": {
    "b2c-dx-mcp": {
      "command": "npx",
      "args": ["-y", "@salesforce/b2c-dx-mcp@latest"]
    }
  }
}

For all projects, use ~/.cursor/mcp.json instead.

See Cursor's MCP documentation.

OpenCode

Add this to opencode.json in your project:

json
{
  "mcp": {
    "b2c-dx-mcp": {
      "type": "local",
      "command": ["npx", "-y", "@salesforce/b2c-dx-mcp@latest"],
      "enabled": true
    }
  }
}

Restart OpenCode. For all projects, use ~/.config/opencode/opencode.json. See OpenCode MCP setup.

Gemini

Run:

bash
gemini mcp add --scope user b2c-dx-mcp -- npx -y @salesforce/b2c-dx-mcp@latest

Start a new Gemini CLI session. To configure the current project only, run it from your project directory with --scope project. See Gemini CLI MCP setup.

No separate skills plugins needed.

Other clients and manual setup →
Skip to content
View as Markdown
View as Markdown

b2c_tooling_sdk.auth ​

Authentication strategies and helpers for the B2C tooling SDK.

Mirrors the @salesforce/b2c-tooling-sdk/auth subpath export. Each strategy implements the AuthStrategy protocol (an async fetch that injects credentials and handles retry/refresh). The persistent session store here reads and writes the same auth-sessions.json file as the B2C CLI, so tokens are shared across the Python and TypeScript tooling.

Classes ​

AccessTokenResponse ​

python
class AccessTokenResponse

Access token response from Account Manager.

Fields

NameType
access_tokenstr
expiresdatetime
scopeslist[str]

DecodedJWT ​

python
class DecodedJWT

A decoded (unverified) JWT.

Fields

NameType
headerdict[str, Any]
payloaddict[str, Any]

AuthStrategy ​

python
class AuthStrategy(Protocol)

Protocol implemented by every authentication strategy.

Implementations must inject the auth header and handle their own 401 retry/refresh inside fetch.

fetch method ​

python
async def fetch(url: str, *, method: str = 'GET', headers: dict[str, str] | None = None, content: Any = None, **kwargs: Any) -> httpx.Response

Perform an authenticated request and return the response.

ScopedAuthStrategy ​

python
class ScopedAuthStrategy(AuthStrategy, Protocol)

An AuthStrategy that can also mint/return tokens and manage scopes.

get_authorization_header method ​

python
async def get_authorization_header() -> str

Return the full Authorization header value (e.g. Bearer ...).

invalidate_token method ​

python
def invalidate_token() -> None

Invalidate the cached token, forcing re-auth on the next request.

with_additional_scopes method ​

python
def with_additional_scopes(additional_scopes: list[str]) -> ScopedAuthStrategy

Return a copy of this strategy with additional_scopes merged in.

get_access_token_for_cascade method ​

python
async def get_access_token_for_cascade(candidates: list[list[str]]) -> str

Resolve a scope cascade, returning the first token Account Manager accepts.

BasicAuthConfig ​

python
class BasicAuthConfig

Basic authentication (username / access-key). Used for WebDAV.

Fields

NameType
usernamestr
passwordstr

OAuthAuthConfig ​

python
class OAuthAuthConfig

OAuth authentication configuration for OCAPI / platform APIs.

Fields

NameTypeDefault
client_idstr
client_secretstr | NoneNone
scopeslist[str] | NoneNone
account_manager_hoststr | NoneNone
jwt_cert_pathstr | NoneNone
jwt_key_pathstr | NoneNone
jwt_passphrasestr | NoneNone
redirect_uristr | NoneNone
open_browserCallable[[str], Awaitable[None]] | NoneNone

ApiKeyAuthConfig ​

python
class ApiKeyAuthConfig

API key authentication (MRT and external services).

Fields

NameTypeDefault
keystr
header_namestr | NoneNone

AuthConfig ​

python
class AuthConfig

Combined authentication configuration used by B2CInstance.

Fields

NameTypeDefault
basicBasicAuthConfig | NoneNone
oauthOAuthAuthConfig | NoneNone
api_keyApiKeyAuthConfig | NoneNone
auth_methodslist[AuthMethod] | NoneNone

AuthCredentials ​

python
class AuthCredentials

Flat credential bundle accepted by resolve_auth_strategy.

Fields

NameTypeDefault
client_idstr | NoneNone
client_secretstr | NoneNone
scopeslist[str] | NoneNone
account_manager_hoststr | NoneNone
usernamestr | NoneNone
passwordstr | NoneNone
api_keystr | NoneNone
api_key_header_namestr | NoneNone
redirect_uristr | NoneNone
open_browserCallable[[str], Awaitable[None]] | NoneNone
extradict[str, Any]field(default_factory=dict)

OAuthStrategy ​

python
class OAuthStrategy

OAuth 2.0 client-credentials authentication strategy.

:example:

python
from b2c_tooling_sdk.auth import OAuthStrategy

auth = OAuthStrategy(OAuthConfig(
    client_id="your-client-id",
    client_secret="your-client-secret",
    scopes=["sfcc.products"],
))
response = await auth.fetch("https://api.example.com/products")

fetch method ​

python
async def fetch(url: str, *, method: str = 'GET', headers: dict[str, str] | None = None, content: Any = None, dispatcher: httpx.AsyncBaseTransport | None = None, **kwargs: Any) -> httpx.Response

Perform an authenticated request, injecting a bearer token and retrying once on a post-success 401.

get_authorization_header method ​

python
async def get_authorization_header() -> str

Return the Authorization header value (Bearer <token>).

get_jwt method ​

python
async def get_jwt() -> DecodedJWT

Return the decoded (unverified) access-token JWT.

get_token_response method ​

python
async def get_token_response() -> AccessTokenResponse

Return the full token response (token + expiry + scopes), using the cache when valid.

invalidate_token method ​

python
def invalidate_token() -> None

Invalidate every cached token for this client/method/AM-host identity.

with_additional_scopes method ​

python
def with_additional_scopes(additional_scopes: list[str]) -> OAuthStrategy

Return a new strategy with additional_scopes merged into the configured scopes.

get_access_token_for_cascade method ​

python
async def get_access_token_for_cascade(candidates: list[list[str]]) -> str

Resolve a scope cascade, returning the first token AM accepts.

Each candidate is merged with this strategy's base scopes. Pass 1 scans the cache for a token satisfying any candidate; pass 2 requests each candidate from AM in order, skipping invalid_scope rejections and rethrowing anything else.

OAuthConfig ​

python
class OAuthConfig

Configuration for OAuthStrategy (client-credentials grant).

JwtOAuthStrategy ​

python
class JwtOAuthStrategy

OAuth 2.0 JWT Bearer authentication strategy (RFC 7523).

Differs from client credentials: uses a public/private key pair instead of a secret, sends a self-signed short-lived JWT as client_assertion in the POST body, and shares the module-level token cache under the jwt method.

fetch method ​

python
async def fetch(url: str, *, method: str = 'GET', headers: dict[str, str] | None = None, content: Any = None, dispatcher: httpx.AsyncBaseTransport | None = None, **kwargs: Any) -> httpx.Response

Perform a request with JWT Bearer auth, retrying once on a post-success 401.

get_authorization_header method ​

python
async def get_authorization_header() -> str

Return the Authorization header value (Bearer <token>).

get_jwt method ​

python
async def get_jwt() -> DecodedJWT

Return the decoded (unverified) access-token JWT.

get_token_response method ​

python
async def get_token_response() -> AccessTokenResponse

Return the full token response, using the cache when valid.

invalidate_token method ​

python
def invalidate_token() -> None

Evict every cached token for this client/AM-host JWT identity.

with_additional_scopes method ​

python
def with_additional_scopes(additional_scopes: list[str]) -> JwtOAuthStrategy

Return a new strategy with additional_scopes merged into the configured scopes.

get_access_token_for_cascade method ​

python
async def get_access_token_for_cascade(candidates: list[list[str]]) -> str

Resolve a scope cascade for the JWT flow (mirrors OAuthStrategy.get_access_token_for_cascade).

JwtOAuthConfig ​

python
class JwtOAuthConfig

Configuration for JwtOAuthStrategy.

PkceOAuthStrategy ​

python
class PkceOAuthStrategy

OAuth 2.0 Authorization Code Flow with PKCE (public clients).

fetch method ​

python
async def fetch(url: str, *, method: str = 'GET', headers: dict[str, str] | None = None, content: Any = None, dispatcher: httpx.AsyncBaseTransport | None = None, **kwargs: Any) -> httpx.Response

Perform a request with PKCE auth, retrying once on a post-success 401.

get_authorization_header method ​

python
async def get_authorization_header() -> str

Return the Authorization header value (Bearer <token>).

get_jwt method ​

python
async def get_jwt() -> DecodedJWT

Return the decoded (unverified) access-token JWT.

get_token_response method ​

python
async def get_token_response() -> AccessTokenResponse

Return the full token response, refreshing or running the browser flow as needed.

invalidate_token method ​

python
def invalidate_token() -> None

Drop only the cached access token; the refresh token is preserved for silent renewal.

PkceOAuthConfig ​

python
class PkceOAuthConfig

Configuration for the OAuth Authorization Code + PKCE flow.

PkceGrantUnsupportedError ​

python
class PkceGrantUnsupportedError(Exception)

Raised when the Authorization Code + PKCE flow fails because the client is not registered for that grant (e.g. a legacy implicit-only public client or a missing/mismatched redirect URI) rather than a transient or user-driven failure.

PkceWithImplicitFallbackStrategy keys its automatic fallback off this type so it retries with the legacy implicit flow ONLY for grant/registration failures — never for user-cancel, state mismatch, or a port-in-use error.

PkceWithImplicitFallbackStrategy ​

python
class PkceWithImplicitFallbackStrategy

Wraps a PkceOAuthStrategy, falling back to implicit on a grant error.

fetch method ​

python
async def fetch(url: str, *, method: str = 'GET', headers: dict[str, str] | None = None, content: Any = None, dispatcher: httpx.AsyncBaseTransport | None = None, **kwargs: Any) -> httpx.Response

Fetch via PKCE, falling back to implicit on a grant-unsupported error.

get_authorization_header method ​

python
async def get_authorization_header() -> str

Return the Authorization header, falling back to implicit on a grant error.

get_jwt method ​

python
async def get_jwt() -> DecodedJWT

Return the decoded access-token JWT, falling back to implicit on a grant error.

get_token_response method ​

python
async def get_token_response() -> AccessTokenResponse

Return the full token response, falling back to implicit on a grant error.

invalidate_token method ​

python
def invalidate_token() -> None

Invalidate cached tokens on both the PKCE and (if present) implicit strategies.

ImplicitOAuthStrategy ​

python
class ImplicitOAuthStrategy

OAuth 2.0 Implicit Grant flow (deprecated; public clients only).

fetch method ​

python
async def fetch(url: str, *, method: str = 'GET', headers: dict[str, str] | None = None, content: Any = None, dispatcher: httpx.AsyncBaseTransport | None = None, **kwargs: Any) -> httpx.Response

Perform a request with implicit-flow auth, retrying once on a post-success 401.

get_authorization_header method ​

python
async def get_authorization_header() -> str

Return the Authorization header value (Bearer <token>).

get_jwt method ​

python
async def get_jwt() -> DecodedJWT

Return the decoded (unverified) access-token JWT.

get_token_response method ​

python
async def get_token_response() -> AccessTokenResponse

Return the full token response, running the browser flow when the cache is stale.

invalidate_token method ​

python
def invalidate_token() -> None

Invalidate the cached token, forcing re-authentication on the next request.

ImplicitOAuthConfig ​

python
class ImplicitOAuthConfig

Configuration for the legacy implicit OAuth flow.

StatefulOAuthStrategy ​

python
class StatefulOAuthStrategy

Auth strategy that uses a persisted access token from the unified store.

No refresh — on expiry/401, the session is cleared and the caller is expected to re-authenticate.

fetch method ​

python
async def fetch(url: str, *, method: str = 'GET', headers: dict[str, str] | None = None, content: Any = None, dispatcher: httpx.AsyncBaseTransport | None = None, **kwargs: Any) -> httpx.Response

Perform a request with the stored token; on 401 clear the session.

get_authorization_header method ​

python
async def get_authorization_header() -> str

Return the Authorization header value (Bearer <token>).

get_token_response method ​

python
async def get_token_response() -> AccessTokenResponse

Return the current token as an AccessTokenResponse (expires/scopes from the JWT).

get_jwt method ​

python
async def get_jwt() -> DecodedJWT

Return the decoded (unverified) access-token JWT.

invalidate_token method ​

python
def invalidate_token() -> None

Delete the persisted session and blank the in-memory access token.

StatefulOAuthStrategyOptions ​

python
class StatefulOAuthStrategyOptions

Options for StatefulOAuthStrategy (kept for API parity with the TS SDK).

BasicAuthStrategy ​

python
class BasicAuthStrategy

Basic authentication strategy.

:example:

python
from b2c_tooling_sdk.auth import BasicAuthStrategy

auth = BasicAuthStrategy("username", "access-key")
response = await auth.fetch("https://webdav.example.com/path")

fetch method ​

python
async def fetch(url: str, *, method: str = 'GET', headers: dict[str, str] | None = None, content: Any = None, dispatcher: httpx.AsyncBaseTransport | None = None, **kwargs: Any) -> httpx.Response

Perform a request with the Authorization: Basic header set.

get_authorization_header method ​

python
async def get_authorization_header() -> str

Return the Authorization: Basic header value.

ApiKeyStrategy ​

python
class ApiKeyStrategy

API key authentication strategy.

:example:

python
# MRT API (Bearer token) -> Authorization: Bearer {key}
auth = ApiKeyStrategy(api_key, "Authorization")

# Custom header -> x-api-key: {key}
auth = ApiKeyStrategy(api_key, "x-api-key")

fetch method ​

python
async def fetch(url: str, *, method: str = 'GET', headers: dict[str, str] | None = None, content: Any = None, dispatcher: httpx.AsyncBaseTransport | None = None, **kwargs: Any) -> httpx.Response

Perform a request with the API-key header set.

get_authorization_header method ​

python
async def get_authorization_header() -> str

Return the header value (Bearer {key} for Authorization, else the raw key).

AvailableAuthMethods ​

python
class AvailableAuthMethods

Result of checking which auth methods have credentials available.

Fields

NameType
availablelist[AuthMethod]
unavailablelist[UnavailableAuthMethod]

UnavailableAuthMethod ​

python
class UnavailableAuthMethod

A method that is missing at least one required credential.

Fields

NameType
methodAuthMethod
reasonstr

AuthMiddleware ​

python
class AuthMiddleware(Protocol)

Middleware for authentication requests (analogous to openapi-fetch middleware).

on_request method ​

python
async def on_request(request: httpx.Request) -> httpx.Request | None

Called before the auth request is sent; may mutate or replace it.

on_response method ​

python
async def on_response(request: httpx.Request, response: httpx.Response) -> httpx.Response | None

Called after the auth response is received; may mutate or replace it.

AuthMiddlewareProvider ​

python
class AuthMiddlewareProvider(Protocol)

Supplies AuthMiddleware for auth requests.

Fields

NameType
namestr

get_middleware method ​

python
def get_middleware() -> AuthMiddleware | None

Return middleware to apply, or None to skip.

AuthMiddlewareRegistry ​

python
class AuthMiddlewareRegistry

Collects middleware from providers, returning them in registration order.

Fields

NameTypeDescription
sizeintNumber of registered providers.

register method ​

python
def register(provider: AuthMiddlewareProvider) -> None

Register a middleware provider.

unregister method ​

python
def unregister(name: str) -> bool

Remove a provider by name; return True if one was removed.

get_middleware method ​

python
def get_middleware() -> list[AuthMiddleware]

Collect middleware from all providers, in registration order.

clear method ​

python
def clear() -> None

Clear all registered providers (primarily for testing).

get_provider_names method ​

python
def get_provider_names() -> list[str]

Return the names of all registered providers.

AuthSession ​

python
class AuthSession

One persisted authentication session, keyed by client_id.

Field names are snake_case in Python but serialize to the camelCase keys the TypeScript SDK writes (clientId, accessToken, refreshToken, ...).

Fields

NameTypeDefault
client_idstr
flowAuthSessionFlow
access_tokenstr
pkce_unsupportedbool | NoneNone
refresh_tokenstr | NoneNone
substr | NoneNone
expires_atstr | NoneNone
scopeslist[str] | NoneNone
account_manager_hoststr | NoneNone
last_used_atstr | NoneNone

to_json method ​

python
def to_json() -> dict[str, Any]

Serialize to a dict with camelCase keys, omitting None fields (matching JSON.stringify).

from_json method ​

python
def from_json(data: dict[str, Any]) -> AuthSession

Build an AuthSession from a camelCase dict written by any backend.

AuthSessionBackend ​

python
class AuthSessionBackend(Protocol)

Pluggable backend for the auth-session store.

FileAuthSessionBackend ​

python
class FileAuthSessionBackend

Default JSON-file backend at <data dir>/auth-sessions.json.

Writes atomically via a temp file + rename, with the directory created 0o700 and the file written 0o600 (matching the TS backend, since the file holds long-lived PKCE refresh tokens).

Fields

NameType
data_dirPath

InMemoryAuthSessionBackend ​

python
class InMemoryAuthSessionBackend

In-memory backend, useful for tests and IDE adapters.

Functions ​

create_user_auth_strategy ​

python
def create_user_auth_strategy(config: PkceOAuthConfig) -> PkceOAuthStrategy | PkceWithImplicitFallbackStrategy

Build the browser-based "user" auth strategy.

Returns a plain PkceOAuthStrategy when the fallback is disabled (SFCC_DISABLE_PKCE_FALLBACK), otherwise a PkceWithImplicitFallbackStrategy.

is_pkce_fallback_disabled ​

python
def is_pkce_fallback_disabled() -> bool

True when SFCC_DISABLE_PKCE_FALLBACK is set to any truthy value.

resolve_auth_strategy ​

python
def resolve_auth_strategy(credentials: AuthCredentials, allowed_methods: list[AuthMethod] | None = None) -> AuthStrategy

Resolve and create the appropriate auth strategy.

Iterates through allowed methods in priority order and returns the first strategy for which the required credentials are available.

Parameters

NameTypeDescription
credentialsAuthCredentialsThe available credentials.
allowed_methodslist[AuthMethod] | NoneAllowed methods in priority order (defaults to ALL_AUTH_METHODS, where PKCE-based user auth is preferred over the deprecated implicit flow).

Raises

  • RuntimeError — if no allowed method has the required credentials.

check_available_auth_methods ​

python
def check_available_auth_methods(credentials: AuthCredentials, allowed_methods: list[AuthMethod] | None = None) -> AvailableAuthMethods

Check which auth methods have the required credentials available.

Parameters

NameTypeDescription
credentialsAuthCredentialsThe available credentials.
allowed_methodslist[AuthMethod] | NoneMethods to check (defaults to ALL_AUTH_METHODS).

Returns: The available and unavailable methods.

encode_basic_client_credentials ​

python
def encode_basic_client_credentials(client_id: str, client_secret: str) -> str

Build the Base64 payload for Authorization: Basic per RFC 6749 §2.3.1.

Parameters

NameTypeDescription
client_idstrThe OAuth client identifier.
client_secretstrThe OAuth client password/secret.

Returns: The Base64 string to place after Basic in the header.

decode_jwt ​

python
def decode_jwt(token: str) -> DecodedJWT

Decode a JWT into its header and payload without verifying the signature.

Raises

  • ValueError — if the token is not a well-formed three-part JWT.

decode_jwt_token_info ​

python
def decode_jwt_token_info(token: str) -> tuple[datetime, list[str]]

Return (expires, scopes) for a token. Propagates decode errors.

extract_jwt_scopes ​

python
def extract_jwt_scopes(payload: dict[str, Any]) -> list[str]

Extract scope from a decoded JWT payload (array or space-delimited string).

is_jwt_token_valid ​

python
def is_jwt_token_valid(token: str, required_scopes: list[str] | None = None, expiry_buffer_sec: int = DEFAULT_EXPIRY_BUFFER_SEC) -> bool

Return True if the token decodes, is unexpired (with buffer), and has all scopes.

get_oauth_cache_key ​

python
def get_oauth_cache_key(client_id: str, method: str, account_manager_host: str, scopes: list[str] | None = None) -> str

Build a token cache key. Includes the auth method to keep grants distinct.

get_cached_oauth_token ​

python
def get_cached_oauth_token(cache_key: str, required_scopes: list[str] | None = None) -> AccessTokenResponse | None

Return a cached token if present, unexpired, and covering required_scopes.

set_cached_oauth_token ​

python
def set_cached_oauth_token(cache_key: str, token_response: AccessTokenResponse) -> None

Store a token in the global cache.

find_cached_token_satisfying ​

python
def find_cached_token_satisfying(identity_prefix: str, required_scopes: list[str]) -> AccessTokenResponse | None

Return the first non-expired cached token (matching identity_prefix) whose scopes ⊇ required_scopes.

Used by cascade resolution: a token granted with broader scopes automatically satisfies a later request needing a narrower scope, with no extra AM round trip.

invalidate_cached_tokens_for_identity ​

python
def invalidate_cached_tokens_for_identity(identity_prefix: str) -> None

Evict every cached token for an identity prefix (host:clientId:method:).

Cascade-resolving strategies cache tokens under merged-scope keys, so deleting only the base key on a 401 would leave a rejected merged token cached. Clearing by identity prefix evicts all of them so the retry re-requests from AM.

reset_oauth_cache_for_testing ​

python
def reset_oauth_cache_for_testing() -> None

Clear the module-level token cache and pending-request map (tests only).

apply_auth_request_middleware ​

python
async def apply_auth_request_middleware(request: httpx.Request, middleware: list[AuthMiddleware]) -> httpx.Request

Apply every on_request hook in order, accumulating modifications.

apply_auth_response_middleware ​

python
async def apply_auth_response_middleware(request: httpx.Request, response: httpx.Response, middleware: list[AuthMiddleware]) -> httpx.Response

Apply every on_response hook in order, accumulating modifications.

get_default_data_dir ​

python
def get_default_data_dir(*, data_directory: str | None = None, environment: dict[str, str] | None = None, home_directory: str | None = None, platform: str | None = None) -> Path

Resolve the shared oclif-compatible B2C data directory (the session store).

Mirrors @oclif/core's Config.dataDir — and the sibling get_b2c_config_directory — so the SDK reads the same auth-sessions.json the b2c CLI writes:

$B2C_DATA_DIR | $XDG_DATA_HOME | (win32 %LOCALAPPDATA%) | ~/.local/share then /b2c.

Note: oclif's data dir uses the XDG ~/.local/share base on macOS too — not ~/Library/Application Support (that path is only oclif's cache dir).

set_auth_session_backend ​

python
def set_auth_session_backend(backend: AuthSessionBackend | None) -> None

Register an auth-session backend. Pass None to fall back to the file backend.

get_auth_session_backend ​

python
def get_auth_session_backend() -> AuthSessionBackend

Return the active backend (lazily creating the file-backed default).

initialize_file_auth_session_store ​

python
def initialize_file_auth_session_store(data_dir: str | os.PathLike[str]) -> None

Install a FileAuthSessionBackend pointed at data_dir.

find_auth_session ​

python
def find_auth_session(client_id: str) -> AuthSession | None

Read the stored session for client_id (or None).

save_auth_session ​

python
def save_auth_session(session: AuthSession) -> None

Write a session, replacing any prior record for the same client_id.

delete_auth_session ​

python
def delete_auth_session(client_id: str) -> None

Delete the session for client_id.

list_auth_sessions ​

python
def list_auth_sessions() -> list[AuthSession]

List all stored sessions (for diagnostics).

clear_all_auth_sessions ​

python
def clear_all_auth_sessions() -> None

Remove every stored session. Used by auth logout.

is_auth_session_token_valid ​

python
def is_auth_session_token_valid(session: AuthSession, required_scopes: list[str] | None = None, expiry_buffer_sec: int = DEFAULT_EXPIRY_BUFFER_SEC, required_client_id: str | None = None) -> bool

Return True if the session's access token is present, unexpired, and in-scope.

Performs no network calls — validity is derived from the JWT exp/scope.

reset_auth_session_store_for_testing ​

python
def reset_auth_session_store_for_testing() -> None

Reset the active backend (tests). The next call falls back to the file default.

Attributes ​

AuthMethod ​

python
AuthMethod = Literal['client-credentials', 'jwt', 'user', 'implicit', 'basic', 'api-key']

ALL_AUTH_METHODS ​

python
ALL_AUTH_METHODS: list[AuthMethod] = ['client-credentials', 'jwt', 'user', 'implicit', 'basic', 'api-key']

DEFAULT_EXPIRY_BUFFER_SEC ​

python
DEFAULT_EXPIRY_BUFFER_SEC = 60

global_auth_middleware_registry ​

python
global_auth_middleware_registry = AuthMiddlewareRegistry()

AuthSessionFlow ​

python
AuthSessionFlow = Literal['pkce', 'implicit', 'client-credentials']