Authentication

archibald.auth.ArcGISAuth

Bases: Auth, ABC

Abstract base class for all archibald authentication implementations.

Subclasses must implement get_token(), which is called on every request. Token caching, refresh logic, and expiry management are the subclass's responsibility. This base class owns only the header injection contract.

__aenter__() async

Enter the async context manager.

__aexit__(*args) async

Exit the async context manager and release resources.

aclose() async

Release any resources held by this auth instance.

Subclasses that hold an internal httpx.AsyncClient should override this method to close it. The base implementation is a no-op.

async_auth_flow(request) async

Inject the Bearer token into the request's Authorization header.

force_refresh() abstractmethod async

Unconditionally refresh the access token.

Called by ArchieClient when a 498/499 response is received. Implementations must fetch a fresh token regardless of any cached state.

get_token() abstractmethod async

Return a valid access token.

Implementations are responsible for caching, refresh, and expiry. This method must always return a token that is ready to use.

archibald.auth.NoAuth

Bases: ArcGISAuth

Authentication implementation for public ESRI services that require no credentials.

async_auth_flow(request) async

Pass the request through without adding any Authorization header.

force_refresh() async

No-op: NoAuth has no token to refresh.

get_token() async

NoAuth does not issue tokens; returns an empty string.

archibald.auth.UserTokenAuth

Bases: ArcGISAuth

Authenticates with an ESRI REST API using the generateToken endpoint.

Lazily initialises an internal httpx.AsyncClient on the first request. Tokens are cached and proactively refreshed before expiry. Safe for use across concurrent requests via an anyio.Lock.

Parameters:

Name	Type	Description	Default
username	str	ESRI account username.	required
password	str	ESRI account password. Stored internally as a SecretStr.	required
base_url	str	Base URL of the portal. Defaults to ArcGIS Online.	ARCGIS_ONLINE_BASE_URL
expiration	int	Token lifetime in minutes. Defaults to 60.	60

aclose() async

Close the internal httpx.AsyncClient if one was created.

force_refresh() async

Invalidate the cached token and fetch a new one immediately.

Intended for use by the client layer when a 498 or 499 is received despite a nominally valid token.

Raises:

Type	Description
TokenRefreshError	If the token cannot be refreshed.

get_token() async

Return a valid token, refreshing if necessary.

Uses a double-checked lock to prevent concurrent refresh races.

Raises:

Type	Description
TokenRefreshError	If the token cannot be obtained or refreshed.