Authentication

altar.access defines authentication only. Authorization, tenancy, and resource policy belong to the host application.

Provisional

Every name in altar.access is provisional. Altar ships only the development-only DevAuthProvider, and no Altar component consumes the contract. The names remain importable, but they may change in a minor release until a public production adapter, a consumer, and conformance coverage exist.

AuthProvider.verify_token is synchronous. An asynchronous host that calls a network-bound provider should run it in a worker thread.

access

Provisional authentication-provider contract.

Authentication extensions should implement :class:AuthProvider through this module. Agent credentials and service-specific clients are not part of this API.

Every name in this module is provisional and listed in __provisional__: it remains importable, but it is excluded from the stable-API commitment. Altar ships only the development-only DevAuthProvider and no component that consumes the contract. The module becomes stable when a public production adapter, an in-repository consumer, documentation, and conformance coverage of that adapter exist.

AuthIdentity dataclass

AuthIdentity(email: str, name: str | None = None)

The verified identity of a caller.

email is the key used to identify a user across the platform, so the provider always lowercases it for consistent matching. name is a display name and may be absent.

AuthProvider

Bases: ABC

Verifies a raw bearer token and returns an AuthIdentity.

Provisional: exported for existing host applications, but excluded from the stable-API commitment until a public production adapter, an in-repository consumer, and conformance coverage exist (see the module docstring).

name is the key the registry uses to identify an adapter — the altar.auth entry-point name such as "dev" or "auth0". Each adapter sets it.

verify_token abstractmethod

verify_token(token: str) -> AuthIdentity

Verify token and return the caller's identity.

This method is synchronous; an asynchronous host that calls a network-bound provider should run it in a worker thread. Raises InvalidTokenError if the token is missing, malformed, or fails verification.

DevAuthProvider

DevAuthProvider(
    email: str | None = None,
    display_name: str | None = None,
)

Bases: AuthProvider

A no-auth provider for local and development use. Provisional, like AuthProvider.

It ignores the token and returns one configured identity. The identity comes from ALTAR_DEV_USER_EMAIL and ALTAR_DEV_USER_NAME, each with a default. Registered under altar.auth as dev, this is core's reference adapter for running without an external auth service.

InvalidTokenError

Bases: Exception

Raised by an AuthProvider when a token is missing, invalid, or expired.

Core does not depend on a web framework, so the HTTP layer translates this into a 401 rather than the provider raising an HTTPException itself.

get_auth_registry

get_auth_registry() -> PluginRegistry[type[AuthProvider]]

Return the shared altar.auth registry.

Provisional, like the AuthProvider contract it resolves; see the module docstring.