satorbis_kit.auth package

class satorbis_kit.auth.Environment(value)[source]

Bases: str, Enum

Named deployment environments supported by the auth layer.

DEV = 'dev'
PROD = 'prod'
class satorbis_kit.auth.OIDCAuth(environment: Environment | str | None = None, application: str | None = None, redirect_port: int = 4200, scopes: str = 'openid profile email offline_access', callback_timeout: int = 300, authorization_url: str | None = None, token_url: str | None = None, verify_jwt: bool = True)[source]

Bases: BaseAuth

Manages the full OIDC Authorization Code + PKCE flow against an OIDC provider, designed for use inside a Jupyter notebook.

Parameters:

  • environment – Target deployment environment. Accepts an Environment member, a plain string ("prod" or "dev"), or None. When None the value of the SATORBIS_ENV environment variable is used; if that is also absent, prod is the default. Example: OIDCAuth(environment="dev").

  • application – Application name used to look up a Zitadel project ID from the environment’s project_ids mapping. When a project ID is found, urn:zitadel:iam:org:project:id:{project_id}:aud is appended to the requested scopes so the token carries the project audience claim. Example: OIDCAuth(application="spatial_engine").

  • redirect_port – Local port for the OAuth callback server. Must match the redirect URI registered with the provider. Default: 4200.

  • scopes – Space-separated OIDC scopes. Include offline_access to receive a refresh token.

  • callback_timeout – Seconds to wait for the browser callback before raising TimeoutError. Default: 300 (5 minutes).

  • authorization_url – Optional. The authorization endpoint URL. If not provided, it will be discovered from the OIDC discovery document.

  • token_url – Optional. The token endpoint URL. If not provided, it will be discovered from the OIDC discovery document.

  • verify_jwt – If True, JWT signature verification is performed using the provider’s JWKS when enforcing email identity. Default: True.

authenticate() → TokenStore[source]

For interactive OIDC flows, use start_login() followed by await_callback(). This method is not directly applicable to interactive browser-based flows.

Raises:

NotImplementedError – Always. Use start_login() + await_callback() instead.

await_callback() → TokenStore[source]

Block until the browser callback is received, exchange the authorization code for tokens, then verify that the authenticated email matches the login_hint from start_login().

Raises:

  • RuntimeError – If start_login() has not been called first.

  • TimeoutError – If no callback is received within callback_timeout seconds.

  • IdentityMismatchError – If the authenticated user’s email does not match the expected login_hint. Tokens are not stored in this case.

refresh_token() → TokenStore[source]

Exchange the refresh token for a new access token (and possibly a new refresh token). Updates tokens in-place.

Providers with refresh token rotation return a new refresh token with each call, which is saved automatically.

Returns:

The updated token store.

Return type:

TokenStore

Raises:

ValueError – If no refresh token is available (e.g. offline_access scope was not requested).

start_login(login_hint: str = '') → str[source]

Generate the PKCE authorization URL and start the local callback server in a background thread.

The login_hint email is remembered and enforced in await_callback() — if the user authenticates as a different identity, IdentityMismatchError is raised and no tokens are stored.

Parameters:

login_hint – Email address to pre-fill on the provider login page. When provided, the authenticated token must match this email.

Returns:

The authorization URL. The user must open it in a browser.

Return type:

str

class satorbis_kit.auth.ServiceAuth(client_id: str, client_secret: str, environment: Environment | str | None = None, scopes: str = 'openid profile email', token_url: str | None = None)[source]

Bases: BaseAuth

Manages the service-account (client-credentials) login flow against an OIDC provider, designed for use inside a Jupyter notebook.

Parameters:

  • client_id – The client ID of the OIDC application.

  • client_secret – The client secret of the OIDC application.

  • environment – Target deployment environment. Accepts an Environment member, a plain string ("prod" or "dev"), or None. When None the value of the SATORBIS_ENV environment variable is used; if that is also absent, prod is the default. Example: ServiceAuth(..., environment="dev").

  • scopes – Space-separated OIDC scopes.

  • token_url – Optional. The token endpoint URL. If not provided, it will be discovered from the OIDC discovery document.

authenticate()[source]

Authenticate using service account (client credentials flow).

Returns:

Token store containing the access token.

Return type:

TokenStore

refresh_token()[source]

Refresh the access token by re-authenticating.

Returns:

Token store containing the new access token.

Return type:

TokenStore

class satorbis_kit.auth.TokenStore(access_token: str | None = None, refresh_token: str | None = None, id_token: str | None = None, token_type: str = 'Bearer', expires_at: float | None = None)[source]

Bases: object

access_token: str | None = None
decode_jwt_payload() → dict[source]

Decode the access token’s JWT payload without signature verification.

static decode_jwt_payload_str(token_str: str) → dict[source]

Base64-decode a JWT payload without verifying the signature.

expires_at: float | None = None
id_token: str | None = None
property is_empty
property is_expired
refresh_token: str | None = None
token_type: str = 'Bearer'
update_from_raw(raw: dict)[source]

Submodules