Auth

Runnable example

python/examples/auth_status.py — read the current Resonite cloud auth state (signed-in user / session expiry), read-only.

resoio.auth.AuthClient

AuthClient(socket_path: str | None = None)

Bases: _BaseClient[AuthStub]

Async client for the Resonite IO Auth service over a UDS.

Use as an async context manager so the gRPC channel closes deterministically.

The password passed to :meth:login is a plaintext secret and is never logged. remember_me=True asks the engine to persist the session; this client itself stores nothing on disk.

Source code in src/resoio/_client.py

def __init__(self, socket_path: str | None = None) -> None:
    # Defer resolution to __aenter__ so env vars patched between
    # construction and connection are honoured, and so resolution
    # errors surface at the connect site.
    self._explicit_path: str | None = socket_path
    self._channel: Channel | None = None
    self._stub: TStub | None = None
    self._resolved_path: str | None = None

login async

login(
    credential: str, password: str, *, totp: str | None = None, remember_me: bool = True
) -> AuthStatus

Sign in to Resonite cloud and return the resulting status.

credential is a username, email, or user ID (U-xxx); password is the plaintext secret (never logged). Pass totp for 2FA-enabled accounts; omitting it on such an account makes the server return gRPC FailedPrecondition. Bad credentials return Unauthenticated. remember_me=True delegates session persistence to the engine.

Source code in src/resoio/auth.py

async def login(
    self,
    credential: str,
    password: str,
    *,
    totp: str | None = None,
    remember_me: bool = True,
) -> AuthStatus:
    """Sign in to Resonite cloud and return the resulting status.

    ``credential`` is a username, email, or user ID (``U-xxx``);
    ``password`` is the plaintext secret (never logged). Pass ``totp`` for
    2FA-enabled accounts; omitting it on such an account makes the server
    return gRPC ``FailedPrecondition``. Bad credentials return
    ``Unauthenticated``. ``remember_me=True`` delegates session
    persistence to the engine.
    """
    stub = self._require_stub()
    request = AuthLoginRequest(
        credential=credential,
        password=password,
        totp=totp,
        remember_me=remember_me,
    )
    return _status_from_proto(await stub.login(request))

logout async

logout() -> AuthStatus

Log out of the current session; returns the updated status.

Idempotent: returns logged_in=False even if no session was active.

Source code in src/resoio/auth.py

async def logout(self) -> AuthStatus:
    """Log out of the current session; returns the updated status.

    Idempotent: returns ``logged_in=False`` even if no session was active.
    """
    stub = self._require_stub()
    return _status_from_proto(await stub.logout(AuthLogoutRequest()))

status async

status() -> AuthStatus

Return the current authentication status without modifying it.

Source code in src/resoio/auth.py

async def status(self) -> AuthStatus:
    """Return the current authentication status without modifying it."""
    stub = self._require_stub()
    return _status_from_proto(await stub.status(AuthStatusRequest()))

resoio.auth.AuthStatus dataclass

AuthStatus(
    logged_in: bool, user_id: str, user_name: str, session_expires_unix_nanos: int
)

Snapshot of the Resonite cloud authentication state.

user_id / user_name are empty and session_expires_unix_nanos is 0 when not logged in.

session_expires property

session_expires: datetime | None

Session expiry as a timezone-aware UTC :class:~datetime.datetime.

None when not logged in or the expiry is unknown (session_expires_unix_nanos is 0). Resolution is microseconds; use session_expires_unix_nanos for the exact nanosecond value.