Documentation

Polaris is a self-hosted authentication library: users, sessions, rotating refresh tokens, MFA, organizations and roles, in your database. It ships as two distributions with one behaviour.

Distribution	Composer packages	Documentation
Polaris for Univeros	univeros/polaris 2.x, the Univeros module built on polaris/core, running every polaris/* plugin by configuration, sending messages off the request through Univeros Messaging and writing its section of the AgentSpec manifests	The Univeros module: install, environment, plugins, your own routes, testing, bin/altair; Polaris for Univeros: the specification, from the data model to the threat model, and the 2.x decisions
Polaris for PHP	polaris/core, polaris/psr15, polaris/pdo, polaris/testing, polaris/cli, polaris/laravel, polaris/symfony, polaris/yii; the plugins (polaris/social, polaris/passkey, polaris/oauth-provider, polaris/mcp, polaris/agents and more); the agent SDK polaris/agent; on npm @polaris-auth/client and @polaris-auth/agent	Polaris for PHP: quick start, packages, framework adapters, CLI, endpoint specs, TypeScript client, agent SDKs; Plugins: the plugin contract and a page per plugin

Polaris for PHP was extracted from the 1.0 Univeros module with every response contract-frozen by recorded fixtures, and univeros/polaris 2.0 is that module rebuilt on polaris/core, so the specification describes both: the flows, MFA, organizations, API reference, security and events pages are what polaris/core implements. Class names in those pages (Univeros\Polaris\Entity\*, Cycle repositories) describe the 1.x shape; in 2.0 the same behaviour lives under the Polaris\ namespaces, and the upgrade guide lists what changes for a 1.x installation.

Where to start

• Univeros host: The Univeros module, then the plugins you need from Plugins; upgrading from 1.x or 2.0, the upgrade guide.
• Laravel, Symfony, Yii or any PSR-15 host: Polaris for PHP, then Laravel, Symfony, Yii or PSR-15.
• Understanding the behaviour: Authentication flows, MFA and OTP, Organizations and RBAC, API reference.
• Reviewing the security posture: Security and threat model, Key rotation.
• Adding sign-in methods, API keys, OAuth, MCP or agents: Plugins, then the plugin’s page (Passkey, Social, OAuth provider, MCP, Agents). On a database Polaris is already installed on, SchemaInstaller::createMissing() from polaris/pdo creates only the tables the new plugin lacks (since 0.10.1).
• Upgrading to 0.11: the polaris/messaging Outbox seam is breaking for a host’s own implementation. Outbox::push(Message, array $alternatives): ?Receipt takes the message and its fallback recipients instead of a closure, a worker delivers them through Sender::dispatch(), and a deferred send answers Receipt::queued(); see Messaging. univeros/polaris’s BusOutbox (“Sending messages off the request” in The Univeros module) is a working queue implementation on the Univeros Messaging bus.
• Coming from Better Auth: the migration map, every Better Auth plugin mapped to a Polaris package and its status.
• Writing a framework adapter: The adapter contract.