Skip to content

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

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, 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

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.

EnvironmentSecretResolver

EnvironmentSecretResolver(
    environ: Mapping[str, str] | None = None,
)

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.

provider class-attribute

provider: str = 'env'

The SecretReference.provider this resolver reads.

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.