Download the PHP package polaris/admin without Composer

polaris/admin

Admin for Polaris for PHP: the operator API over users, sessions, MFA, organizations, audit drains and statistics, for admin users and API keys, every action audited. API-only: a dashboard, a support tool or an integration talks to /admin/*; hosts add nothing beyond the plugin.

polaris/audit is required and must be registered too: every admin action is an admin.* event in its store, and the statistics come from its tables. In Laravel, Symfony and Yii both instances go in the adapter's plugins configuration; the two tables (polaris_admin_grant, polaris_admin_key) join polaris:install, schema:create and schema:diff, the routes join the route table.

Principals

Three kinds of caller reach the admin routes, resolved by the plugin's middleware from the Authorization header; the routes are declared auth: public so core's bearer middleware leaves API keys alone.

• A superadmin: a user holding core's global superadmin role is an owner on the instance, with no grant.
• An admin user: a Polaris user with a grant in polaris_admin_grant (one per user; a new grant replaces it): a role, a scope (instance or one organization id), an optional expiry. Created with polaris admin:grant <email> <role> or POST /admin/grants. The user calls the routes with their usual access token.
• An API key: polaris_admin_key, a role, a scope, an optional IP allowlist (addresses or CIDR blocks) and expiry; pak_ and 256 random bits, stored as a keyed hash, shown once. Created with polaris admin:key <name> <role> or POST /admin/keys (owners). Sent as Authorization: Bearer pak_....

An impersonation token (below) never reaches the admin routes (403 admin/impersonation_denied); a disabled user is no operator; a lapsed grant or key is refused (401 admin/unauthorized).

The role matrix, deny by default, each role including the ones below it:

An organization-scoped principal (a grant or key whose scope is an organization id) may call the organization routes for that organization only (read it, its drains, its audit trail; delete it, set its members' roles; create keys and grants scoped to it); the user, key, grant and stats routes need the instance scope (403 admin/forbidden).

Routes

All under /admin. Errors are RFC 9457 problem documents (admin/unauthorized, admin/forbidden, admin/impersonation_denied, admin/not_found, admin/conflict, admin/invalid_input) that also carry core's error and message. Lists are oldest first (ids are UUID v7) and cursor-paginated (cursor is the next_cursor of the previous page; limit 50 by default, 200 at most).

Impersonation

POST /admin/users/{id}/impersonate answers an access token whose sub is the user, with amr: ["impersonation"], mfa: false, the impersonated_by claim (the operator's id) and impersonator_type, and no session (sid) behind it: it cannot be refreshed, stepped up, switched to an organization or logged out, so it lives exactly one access-token TTL (auth.access_token.ttl, 15 minutes by default). It reads and acts as the user on core's routes, never on the admin routes; a superadmin cannot be impersonated; a disabled account is refused. Hosts render a banner from the claim.

Audit

Every mutation is recorded through polaris/audit as admin.<action> (admin.user_banned, admin.password_set, admin.user_impersonated, admin.session_revoked, admin.mfa_reset, admin.member_roles_changed, admin.organization_deleted, admin.drain_created, admin.key_created, admin.grant_created, ...), the operator as actor (actor_type admin for a user, api_key for a key), the target as subject, the operator's role and scope in data, beside the core event the action emits (user.disabled, mfa.factor_removed, ...). GET /audit/types lists the names.

CLI

polaris admin:key <name> <role> [--scope=] [--allow=cidr,...] [--expires=] prints the key once; polaris admin:grant <email> <role> [--scope=] [--expires=] grants a role. Both take --bootstrap=<file> (or POLARIS_BOOTSTRAP) naming the application, as the other Polaris commands.

License

MIT. Polaris for PHP is created and maintained by 2am.tech.