Core API Reference¶
astraauth.core
¶
Modules:
| Name | Description |
|---|---|
authorization |
|
errors |
|
events |
|
oauth |
|
sessions |
|
authorization
¶
Modules:
| Name | Description |
|---|---|
exceptions |
|
scope_policy |
|
exceptions
¶
Classes:
| Name | Description |
|---|---|
AuthorizationError |
Base class for authorization failures. |
PermissionDeniedError |
Raised when a subject lacks a required permission. |
RoleNotFoundError |
Raised when a referenced role does not exist. |
StepUpRequiredError |
Raised when MFA step-up is required before allowing access. |
TenantIsolationError |
Raised when tenant context is invalid or missing. |
AuthorizationError
¶
Bases: Exception
Base class for authorization failures.
PermissionDeniedError
¶
Bases: AuthorizationError
Raised when a subject lacks a required permission.
RoleNotFoundError
¶
Bases: AuthorizationError
Raised when a referenced role does not exist.
StepUpRequiredError
¶
Bases: AuthorizationError
Raised when MFA step-up is required before allowing access.
TenantIsolationError
¶
Bases: AuthorizationError
Raised when tenant context is invalid or missing.
scope_policy
¶
Classes:
| Name | Description |
|---|---|
DefaultScopePolicy |
Maps permissions to OAuth scopes. |
DefaultScopePolicy(permission_scope_map, *, strict_mode=True)
¶
Maps permissions to OAuth scopes.
strict_mode
If True, any unauthorized requested scope causes failure. If False, unauthorized scopes are silently dropped.
errors
¶
events
¶
Modules:
| Name | Description |
|---|---|
redis_pubsub |
|
zeromq_pubsub |
|
Classes:
| Name | Description |
|---|---|
RedisPubSubEventBus |
Publish-only Redis event bus. |
ZeroMQPubSubEventBus |
Publish-only ZeroMQ event bus. |
RedisPubSubEventBus(client, *, channel_prefix='astraauth:events:')
¶
Bases: EventBus
Publish-only Redis event bus.
Subscription is expected to be handled by an external worker/process that consumes Redis pub/sub and dispatches handlers.
ZeroMQPubSubEventBus(*, endpoint='tcp://127.0.0.1:5556', bind=True)
¶
Bases: EventBus
Publish-only ZeroMQ event bus.
Subscription is expected to be handled by dedicated subscriber processes using ZeroMQ SUB sockets.
redis_pubsub
¶
Classes:
| Name | Description |
|---|---|
RedisPubSubEventBus |
Publish-only Redis event bus. |
RedisPubSubEventBus(client, *, channel_prefix='astraauth:events:')
¶
Bases: EventBus
Publish-only Redis event bus.
Subscription is expected to be handled by an external worker/process that consumes Redis pub/sub and dispatches handlers.
zeromq_pubsub
¶
Classes:
| Name | Description |
|---|---|
ZeroMQPubSubEventBus |
Publish-only ZeroMQ event bus. |
ZeroMQPubSubEventBus(*, endpoint='tcp://127.0.0.1:5556', bind=True)
¶
Bases: EventBus
Publish-only ZeroMQ event bus.
Subscription is expected to be handled by dedicated subscriber processes using ZeroMQ SUB sockets.
oauth
¶
Modules:
| Name | Description |
|---|---|
errors |
|
models |
|
oidc |
|
pkce |
|
services |
|
Classes:
| Name | Description |
|---|---|
AuthorizationCode |
Represents an issued authorization code (one-time use). |
OAuthError |
Base class for OAuth/OIDC domain errors. |
PKCEParams |
Holds PKCE parameters for OAuth 2.1 Authorization Code flow. |
Subject |
Represents the authenticated end-user (or principal). |
AuthorizationCode(code, client_id, tenant_id, subject_id, redirect_uri, scopes, issued_at, expires_at, pkce, nonce=None, used=False)
dataclass
¶
Represents an issued authorization code (one-time use).
OAuthError(description=None)
¶
Bases: Exception
Base class for OAuth/OIDC domain errors.
PKCEParams(code_challenge, code_challenge_method)
dataclass
¶
Holds PKCE parameters for OAuth 2.1 Authorization Code flow.
Subject(subject_id, tenants=set(), username=None, email=None)
dataclass
¶
Represents the authenticated end-user (or principal).
errors
¶
Classes:
| Name | Description |
|---|---|
OAuthError |
Base class for OAuth/OIDC domain errors. |
OAuthError(description=None)
¶
Bases: Exception
Base class for OAuth/OIDC domain errors.
models
¶
Classes:
| Name | Description |
|---|---|
AuthorizationCode |
Represents an issued authorization code (one-time use). |
PKCEParams |
Holds PKCE parameters for OAuth 2.1 Authorization Code flow. |
Subject |
Represents the authenticated end-user (or principal). |
TokenRequestContext |
Captures the validated context for a token exchange. |
AuthorizationCode(code, client_id, tenant_id, subject_id, redirect_uri, scopes, issued_at, expires_at, pkce, nonce=None, used=False)
dataclass
¶
Represents an issued authorization code (one-time use).
PKCEParams(code_challenge, code_challenge_method)
dataclass
¶
Holds PKCE parameters for OAuth 2.1 Authorization Code flow.
Subject(subject_id, tenants=set(), username=None, email=None)
dataclass
¶
Represents the authenticated end-user (or principal).
TokenRequestContext(client, subject, scopes, nonce, auth_time=None)
dataclass
¶
Captures the validated context for a token exchange.
oidc
¶
Functions:
| Name | Description |
|---|---|
build_id_token_claims |
Build OIDC ID Token claims with strict rules. |
build_id_token_claims(*, ctx, issuer, ttl_seconds)
¶
Build OIDC ID Token claims with strict rules.
pkce
¶
Functions:
| Name | Description |
|---|---|
compute_code_challenge |
Compute code_challenge from code_verifier using S256 (OAuth 2.1 only). |
generate_code_verifier |
Generate a high-entropy code_verifier per RFC 7636. |
verify_pkce |
Verify that code_verifier matches the stored code_challenge. |
compute_code_challenge(verifier, method='S256')
¶
Compute code_challenge from code_verifier using S256 (OAuth 2.1 only).
generate_code_verifier(length=64)
¶
Generate a high-entropy code_verifier per RFC 7636. Uses URL-safe characters without padding.
verify_pkce(*, code_verifier, code_challenge, code_challenge_method='S256')
¶
Verify that code_verifier matches the stored code_challenge. Constant-time comparison is used to avoid timing leaks.
services
¶
Functions:
| Name | Description |
|---|---|
exchange_code_for_tokens |
Validates the authorization code + PKCE and mints tokens. |
exchange_code_for_tokens(*, code, client_id, redirect_uri, code_verifier, clients, subjects, codes, token_manager, access_token_audience)
¶
Validates the authorization code + PKCE and mints tokens.
sessions
¶
Modules:
| Name | Description |
|---|---|
models |
|
services |
|
Classes:
| Name | Description |
|---|---|
Session |
|
Session(session_id, subject_id, tenant_id, client_id, requested_scopes, created_at, expires_at, revoked=False, version=1, acr=1, amr=(), authenticated_at=None, upgraded_at=None)
dataclass
¶
models
¶
services
¶
Functions:
| Name | Description |
|---|---|
issue_session_and_refresh_token |
Create a new session and issue encrypted refresh token. |
rotate_refresh_token |
Validate refresh token, rotate session, issue new refresh token. |
issue_session_and_refresh_token(*, subject_id, client_id, tenant_id, requested_scopes, session_store, token_manager, session_ttl_seconds, initial_acr=1, initial_amr=None, event_bus=None)
¶
Create a new session and issue encrypted refresh token.
rotate_refresh_token(*, refresh_token, session_store, token_manager, session_ttl_seconds, event_bus=None)
¶
Validate refresh token, rotate session, issue new refresh token.