Authentication

Providers

cdse.auth.providers

Authentication providers.

A provider describes how to obtain the first token from the CDSE identity service. It does not perform any network request itself; it only supplies the form fields for the grant. The :class:~cdse.auth.manager.TokenManager owns the actual exchange and the subsequent refreshes.

AuthProvider

Bases: ABC

Base class for the supported OAuth grant types.

grant_data abstractmethod

grant_data() -> dict[str, str]

Return the form fields for the initial token request.

PasswordAuth

PasswordAuth(
    username: str,
    password: str,
    *,
    totp: str | None = None,
    client_id: str = DEFAULT_CLIENT_ID,
)

Bases: AuthProvider

Authenticate with a username and password (resource owner grant).

RefreshTokenAuth

RefreshTokenAuth(
    refresh_token: str,
    *,
    client_id: str = DEFAULT_CLIENT_ID,
)

Bases: AuthProvider

Authenticate with a refresh token obtained elsewhere.

A full re authentication is not possible because the original credentials are not held, so once the refresh token expires the session ends.

ClientCredentialsAuth

ClientCredentialsAuth(client_id: str, client_secret: str)

Bases: AuthProvider

Authenticate a registered machine client (client credentials grant).

No refresh token is issued for this grant. When the access token expires the manager simply requests a new one, which this provider always can do.

Token management

cdse.auth.manager.TokenManager

TokenManager(
    provider: AuthProvider,
    *,
    http: Client,
    token_url: str,
    store: TokenStore | None = None,
    expiry_skew: float = 30.0,
)

Obtain and keep an access token valid for the configured provider.

authorization_header

authorization_header() -> str

Return a valid Authorization header value, refreshing if needed.

force_refresh

force_refresh() -> str

Force a token renewal, used after an unexpected 401 response.

clear

clear() -> None

Discard any cached tokens.

Token storage

cdse.auth.store

Token storage.

The :class:TokenSet holds the live credentials, and :class:TokenStore defines how they are persisted. The library defaults to an in memory store so that importing and using the client never touches the filesystem. The command line layer provides a file backed store so that a login survives across separate process invocations.

TokenSet

Bases: BaseModel

A set of OAuth tokens together with their absolute expiry times.

authorization_header property

authorization_header: str

The value to send in the Authorization request header.

access_valid

access_valid(skew: float = 0.0) -> bool

Return whether the access token is still usable.

Parameters:

Name	Type	Description	Default
skew	float	Treat the token as expired this many seconds early.	0.0

refresh_valid

refresh_valid(skew: float = 0.0) -> bool

Return whether a refresh token grant can still succeed.

TokenStore

Bases: ABC

Abstract storage for a :class:TokenSet.

load abstractmethod

load() -> TokenSet | None

Return the stored tokens, or None when nothing is stored.

save abstractmethod

save(tokens: TokenSet) -> None

Persist the given tokens, replacing anything stored before.

clear abstractmethod

clear() -> None

Remove any stored tokens.

MemoryTokenStore

MemoryTokenStore()

Bases: TokenStore

Keep tokens in memory for the lifetime of the process.

FileTokenStore

FileTokenStore(path: Path)

Bases: TokenStore

Persist tokens to a JSON file with owner only permissions.

This lets a command line login survive across separate process invocations. The file is written with mode 0o600 so that other users cannot read the stored tokens.