API reference

All core symbols are available from authwave. Start with Quick start guide for a complete setup.

Authenticator

Authenticator(client_key, current_uri_path, authwave_host='login.authwave.com',
              session=session, redirect_handler=None, on_authenticated=None)

Construction restores stored identity and processes incoming responses. on_authenticated accepts AuthUser and returns synchronously. The client can redirect during construction.

Method	Behavior
is_logged_in() -> bool	Reports whether this instance has a user.
get_auth_user() -> AuthUser	Returns the identity or a not-logged-in error.
login(token=None)	Stores token and redirects; no-op when logged in.
logout(redirect_to=None, token=None)	Clears identity and starts provider logout.
set_return_uri(uri)	Sets subsequent login and default logout destinations.
get_login_uri(token)	Builds a URI without storing or redirecting.
get_admin_uri()	Returns provider administration URI.
fake_login(user_id, email=None, redirect_to="/")	Development-only synthetic login.
get_user()	Deprecated compatibility getter.

AuthUser

AuthUser(id, email) is a frozen identity snapshot with read-only id and email. User is a deprecated subclass. get_user() emits DeprecationWarning.

Session and redirect contracts

GlobalSessionContainer(mapping) / SessionArrayWrapper(mapping) provides get, set, contains, remove. Stored dictionaries are rehydrated into SessionData. SessionData(token=None, data=None, return_query=None) exposes get_token, get_data, get_return_query, has_invoked_authentication_callback, mark_authentication_callback_invoked, and to_dict/from_dict.

RedirectHandler.redirect(uri, code=303) raises RedirectSignal with uri and code. The runtime catches the signal, saves and responds. Missing token or data raises NotLoggedInException.

SessionOptions(store, cookie_name='authwave.sid', secure_cookie=True, ttl_seconds=86400) configures runtime sessions. SessionStore.load(id) returns a dictionary or None; save(id, data, expires_at) stores it with a Unix-seconds expiry. See Sessions and redirects for framework adapters.

Supporting exchange objects

Token(secret, session_iv=None, iv=None) exposes get_iv(), get_secret_iv(), generate_request_cipher(message=''), and decode(base64cipher). InitVector provides get_bytes(), with_bytes() and base64 string conversion. CipherText provides bytes and base64 string conversion. Token.to_dict()/from_dict() support server-side persistence.

LoginUri(token, current_path, deployment_id, base_remote_uri=...), LogoutUri(..., redirect_to=None) and AdminUri(base_remote_uri) extend BaseProviderUri. Uri is string-compatible and provides query/path/host/scheme/port accessors, with_query() and without_query_value().

UserResponseData(id, email, message=None) exposes get_id(), get_email() and inherited get_message(). The separate low-level token decoder uses the request IV and accepts uuid or id; normal authentication uses the session IV and id. Both read email and ignore extra fields.

Exceptions

AuthwaveException is the base of SessionNotStartedException, NotLoggedInException, InsecureProtocolException, InvalidUserDataSerializationException, EncryptionFailureException and DecryptionFailureException. ResponseCipherDecryptionException is a compatibility declaration; normal cipher failures use DecryptionFailureException. Application callback exceptions propagate.