Client

Main entrypoint for Spark RESO Web API access.

Parameters:

Name	Type	Description	Default
access_token	str | None	Direct bearer token or already-issued OIDC access token.	None
auth	TokenAuthStrategy | None	Optional pre-built auth strategy.	None
client_id	str | None	Spark OAuth client ID for OIDC workflows.	None
client_secret	str | None	Spark OAuth client secret for OIDC workflows.	None
redirect_uri	str | None	Redirect URI registered with Spark for OIDC.	None
refresh_token	str | None	Optional OIDC refresh token.	None
id_token	str | None	Optional OIDC ID token.	None
expires_in	int | None	Optional access-token lifetime in seconds.	None
base_url	str	Base URL for RESO requests.	DEFAULT_BASE_URL
timeout_seconds	float	Default request timeout in seconds.	DEFAULT_TIMEOUT_SECONDS
max_retries	int	Number of retries for transient failures.	DEFAULT_MAX_RETRIES
retry_backoff_seconds	float	Initial backoff delay for retries.	DEFAULT_RETRY_BACKOFF_SECONDS
load_dotenv	bool	Whether to load environment variables from a .env file.	False
user_agent	str	User-Agent header to apply to requests.	DEFAULT_USER_AGENT
extra_headers	Mapping[str, str] | None	Additional headers to include with every request.	None

green_verification property

Access the GreenVerification property subresource client.

lookup property

Access the Lookup resource client.

media property

Access the Media property subresource client.

members property

Access the Member resource client.

offices property

Access the Office resource client.

openhouses property

Access the OpenHouse resource client.

power_production property

Access the PowerProduction property subresource client.

properties property

Access the Property resource client.

rooms property

Access the Room property subresource client.

units property

Access the Unit property subresource client.

build_authorization_url(*, state, nonce, scopes=None, response_type='code')

Build the Spark OIDC authorization URL for user sign-in.

Parameters:

Name	Type	Description	Default
state	str	Opaque CSRF protection value.	required
nonce	str	OIDC nonce.	required
scopes	tuple[str, ...] | None	Optional explicit scopes. Defaults to openid.	None
response_type	str	OIDC response type. Spark uses code.	'code'

Returns:

Type	Description
str	A redirect URL for Spark's authorization endpoint.

Raises:

Type	Description
ConfigurationError	If the client is not configured for OIDC.

exchange_oidc_code(code, *, timeout_seconds=None)

Exchange a Spark OIDC authorization code for tokens.

Parameters:

Name	Type	Description	Default
code	str	Authorization code returned by Spark.	required
timeout_seconds	float | None	Optional per-request timeout override.	None

Returns:

Type	Description
AuthTokens	The token set returned by Spark.

Raises:

Type	Description
ConfigurationError	If OIDC is not configured for this client.

get_metadata(*, timeout_seconds=None)

Fetch the RESO metadata document as XML.

Parameters:

Name	Type	Description	Default
timeout_seconds	float | None	Optional per-request timeout override.	None

Returns:

Type	Description
str	The raw metadata XML document.

refresh_oidc_tokens(*, timeout_seconds=None)

Refresh the current Spark OIDC access token.

Parameters:

Name	Type	Description	Default
timeout_seconds	float | None	Optional per-request timeout override.	None

Returns:

Type	Description
AuthTokens	The refreshed token set.

Raises:

Type	Description
ConfigurationError	If OIDC is not configured for this client.

revoke_oidc_token(*, token=None, timeout_seconds=None)

Revoke a Spark OIDC token.

Parameters:

Name	Type	Description	Default
token	str | None	Specific token to revoke. Defaults to the current access token.	None
timeout_seconds	float | None	Optional per-request timeout override.	None

Raises:

Type	Description
ConfigurationError	If OIDC is not configured for this client.