API reference

This page summarises the public client API. Start with the Quick start guide for a complete application setup.

Authenticator

Authwave\Authenticator has the following constructor:

public function __construct(
	string $clientKey,
	string|Psr\Http\Message\UriInterface $currentUriPath,
	string $authwaveHost = "login.authwave.com",
	?GT\Session\SessionContainer $session = null,
	?Authwave\RedirectHandler $redirectHandler = null,
	?callable $onAuthenticated = null,
)

Construction restores session data and processes an incoming response. It may invoke the callback and redirect before returning.

Method	Behaviour
isLoggedIn(): bool	Reports whether this instance has a user.
getAuthUser(): AuthUser	Returns the user, or throws NotLoggedInException.
login(?Token $token = null): void	Stores a token and redirects; returns immediately if already logged in.
logout(null|string|Psr\Http\Message\UriInterface $redirectTo = null, ?Token $token = null): void	Clears stored and in-memory authentication, then starts provider logout. Uses the explicit destination, then a configured return URI, then the provider default. The default fake email uses local logout. See Logging out.
setReturnUri(string $uri): void	Sets the requested login destination and the default logout destination. See Provider configuration and return URIs.
getLoginUri(Token $token): ProviderUri\BaseProviderUri	Builds a login URI without storing the token or redirecting.
getAdminUri(): Psr\Http\Message\UriInterface	Builds the provider's /admin/ URI.
fakeLogin(string $userId, ?string $email = null, string $redirectTo = "/"): void	Stores synthetic user data and redirects. Development use only.
getUser(): User	Deprecated compatibility method; emits E_USER_DEPRECATED.

The callback accepts an AuthUser. See Responding to a new authentication for timing and failure behaviour.

AuthUser

Authwave\AuthUser is constructed with string $id, string $email.

• public readonly string $id
• public readonly string $email

Authwave\User is a deprecated subclass retained for compatibility.

Session and redirect contracts

GlobalSessionContainer wraps an existing native session. Supplied containers implement GT\Session\SessionContainer:

• get(string $key): mixed
• set(string $key, mixed $value): void
• contains(string $key): bool
• remove(string $key): void

RedirectHandler::redirect(UriInterface $uri, int $code = 303): void sends a redirect and exits by default. See Sessions and redirects.

SessionData accepts an optional Token, ResponseData\BaseResponseData and ?string $returnQuery. Its methods are getToken(), getData(), getReturnQuery(), hasInvokedAuthenticationCallback() and markAuthenticationCallbackInvoked(). The saved query string is used when removing the authentication response from the URI. Reading an absent token or response throws NotLoggedInException.

Supporting exchange objects

Token accepts a secret string and optional session and request GT\Cipher\InitVector objects. getIv() and getSecretIv() return those vectors. generateRequestCipher(string $message = "") returns a GT\Cipher\CipherText.

Token::decode(string $base64cipher) is a separate lower-level decoder. It uses the request IV and accepts uuid or id. The authenticator's return processing instead uses the secret session IV and reads id, email. Use the authenticator for the normal login flow rather than substituting this decoder.

The ProviderUri namespace contains LoginUri, LogoutUri, AdminUri and their abstract BaseProviderUri. These extend the HTTP URI implementation and build the provider requests described in Provider configuration and return URIs.

ResponseData\UserResponseData exposes getId() and getEmail(). Its base class exposes getMessage(): ?string. Application code normally uses AuthUser instead.

Exceptions

AuthwaveException extends RuntimeException and is the base of the client's exception classes.

• SessionNotStartedException: the default session container cannot find $_SESSION.
• NotLoggedInException: requested user, token or response data is absent.
• InsecureProtocolException: a provider URI uses a disallowed scheme.
• InvalidUserDataSerializationException: Token::decode() rejects the decoded data shape.
• ResponseCipherDecryptionException: declared, but not currently thrown by the authenticator's response-processing path.

Dependency exceptions and application callback exceptions can propagate separately. See Troubleshooting for common failures.