Authentication¶
altar.access defines authentication providers, and EnvironmentSecretResolver, which reads a model's credential
from the environment variable its SecretReference names
(Give a hosted model its credentials). Authorization,
tenancy and resource policy belong to your own application.
Provisional: every name in this module is provisional. Altar ships only the development-only
DevAuthProvider, and no Altar component uses the provider contract. See Provisional names.
AuthProvider.verify_token is synchronous. An asynchronous application that calls a network-bound provider should run it
in a worker thread.
access
¶
Provisional authentication-provider contract, and the environment-variable secret resolver.
Authentication extensions should implement :class:AuthProvider through this module. Agent credentials
and service-specific clients are not part of this API. :class:EnvironmentSecretResolver resolves a model's
SecretReference from the environment; altar run passes it to inline models.
Every name in this module is provisional and listed in __provisional__: it remains importable, and it is
expected to change. Altar ships only the development-only DevAuthProvider and no
component that consumes the contract.
AuthIdentity
dataclass
¶
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, and expected to change (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
¶
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.
EnvironmentSecretResolver
¶
Resolve a model's SecretReference to the value of an environment variable. Provisional.
A reference with provider "env" names the variable: SecretReference(provider="env",
name="ALPHAGENOME_API_KEY") resolves to $ALPHAGENOME_API_KEY. A run spec carries only that reference, in a
model's configuration, and altar run passes this resolver to every inline model, so the key itself stays in
the environment.
An instance is a SecretResolver: call it with a reference to get the value. It raises ValueError for a
reference to another provider or with a version, which an environment variable does not have, and
LookupError naming the variable when it is unset or empty. environ replaces os.environ, for tests.
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.