ds_fetch_py_sdk.auth

Authentication against the AI Commons identity server.

• BearerToken: a platform JWT you already have.

• BrowserLogin: OAuth authorization code + PKCE in the browser, including enterprise SSO.

• PasswordLogin: email and password at /auth/login/, with TOTP MFA when enabled.

• ClientCredentials: OAuth client credentials, for machines.

Every flow signs in at the environment’s issuer, never at one a server names. OAuth flows read its endpoints from its authorization-server metadata (RFC 8414), which must name that issuer, and bind tokens to the API with resource (RFC 8707).

Module Contents

class ds_fetch_py_sdk.auth.BearerToken(token: str)

Bases: httpx.Auth

A platform JWT you already have.

auth_flow(request: httpx.Request) → collections.abc.Generator[httpx.Request, httpx.Response, None]

Execute the authentication flow.

To dispatch a request, yield it:

` yield request `

The client will .send() the response back into the flow generator. You can access it like so:

` response = yield request `

A return (or reaching the end of the generator) will result in the client returning the last response obtained from the server.

You can dispatch as many requests as is necessary.

ds_fetch_py_sdk.auth.default_cache() → pathlib.Path

Where sessions are cached: $XDG_CONFIG_HOME/aic/credentials.json, default ~/.config.

class ds_fetch_py_sdk.auth.TokenAuth(*, issuer: str | None = None, cache: pathlib.Path | bool = False)

Bases: httpx.Auth

A session with the identity server: acquires, caches and renews tokens, and retries once on 401.

Sessions are cached per environment in default_cache(), or at cache; cache=False keeps them in memory.

login() → None

Sign in now, replacing any cached session.

logout() → None

Forget the session, in memory and in the cache.

auth_flow(request: httpx.Request) → collections.abc.Generator[httpx.Request, httpx.Response, None]

Execute the authentication flow.

To dispatch a request, yield it:

` yield request `

The client will .send() the response back into the flow generator. You can access it like so:

` response = yield request `

A return (or reaching the end of the generator) will result in the client returning the last response obtained from the server.

You can dispatch as many requests as is necessary.

class ds_fetch_py_sdk.auth.OAuth(*, scope: str = 'openid read', **kwargs: Any)

Bases: TokenAuth

OAuth 2.1 against the identity server, with endpoints from RFC 8414 metadata.

property metadata: dict[str, Any]

The identity server’s RFC 8414 metadata, checked to be its own and to use HTTPS.

class ds_fetch_py_sdk.auth.ClientCredentials(client_id: str, client_secret: str, **kwargs: Any)

Bases: OAuth

Machine-to-machine sign-in with a registered client id and secret.

class ds_fetch_py_sdk.auth.BrowserLogin(*, client_id: str | None = None, port: int = 8976, cache: pathlib.Path | bool = True, open_browser: bool = True, on_url: collections.abc.Callable[[str], None] | None = None, timeout: float = 300, **kwargs: Any)

Bases: OAuth

Interactive sign-in in the browser, including enterprise SSO.

Uses authorization code with PKCE on a loopback redirect. Without a client_id the SDK registers a public client (RFC 7591) and caches its id with the session. on_url receives the sign-in URL, for when the browser cannot be opened; it defaults to writing it to stderr.

class ds_fetch_py_sdk.auth.PasswordLogin(email: str | None = None, password: str | None = None, *, mfa_code: str | collections.abc.Callable[[int], str] | None = None, cache: pathlib.Path | bool = True, **kwargs: Any)

Bases: TokenAuth

Sign in with email and password at the identity server’s /auth/login/.

When the account has MFA, mfa_code supplies the TOTP code: a string, or a callable that receives the number of digits and returns the code. The session is renewed with its refresh token; once that expires, signing in again needs the password.

ds_fetch_py_sdk.auth.cached_session(env: ds_fetch_py_sdk.env.Environment, cache: pathlib.Path | None = None) → TokenAuth | None

The cached sign-in for env, as the auth that created it, or None.