Skip to content

API reference

Jump to bottom
Greg Bowler edited this page Oct 30, 2026 · 3 revisions

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 and an optional array<string, string> $kvp = [].

  • public readonly string $id
  • public readonly string $email
  • getData(string $key): ?string
  • getKvp(): array returning array<string, string>

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 with an optional fields array. The authenticator's return processing instead uses the secret session IV and reads id, email and optional kvp. 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(), getEmail(), getField(string $name) and getAllFields(). 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.

Authwave’s PHP client connects your application to an Authwave provider.

Clone this wiki locally
⌂ Proxy