Headless, Action-first user management for Laravel. Every operation is a single Action class, reachable from PHP, a JSON API, an MCP server, and the Atrium dashboard.
- User create, update, delete and listing on your own user model
- Profiles (display name, avatar, timezone, locale, bio, meta) in a side table, so your
userstable is never altered - An active / suspended / deactivated lifecycle with a
roster.activemiddleware - Organizations with teams, members, email invitations, optional domain auto-join, and a per-user current organization/team
- Roles and permissions at global, organization and team scope, resolved through Laravel's Gate (
$user->can(),@can) - Every change recorded in the suite-wide audit log of
refactor-circus/keen, when installed, which adds each record's history to its Atrium page - Impersonation through one-time links, with time limits, a banner, blocked abilities and a full audit trail (with refactor-circus/keen)
- Extension seams for other packages: single sign-on and SCIM provisioning per organization come from
refactor-circus/guardian(see SSO and SCIM)
composer require refactor-circus/rosterPublish the config and migrations, then migrate:
php artisan vendor:publish --tag="roster-config"
php artisan vendor:publish --tag="roster-migrations"
php artisan migrateSet roster.users.key_type (int, ulid or uuid) to match your user model's primary key before migrating, because it decides the type of the roster_profiles.user_id column.
Every table name is configurable under roster.tables, keyed by what it holds (organizations, memberships, team_members, permission_role, ...). Rename them before migrating: the migrations, models, validation rules and queries all read the same keys, and a published config that lists only some tables keeps the defaults for the rest.
'tables' => [
'organizations' => 'crm_organizations',
'memberships' => 'crm_memberships',
],users only names the table of Roster's ready-made UserModel (and its opt-in migration); your own user model keeps its table. keen:import-roster reads the old audit log from its default table names.
The views and translations can be published with roster-views and roster-lang.
The Atrium dashboard is optional. Roster's Actions, HTTP API, MCP server, invitation page and impersonation banner work without it. For Roster's admin screens, widgets and search, install it too:
composer require refactor-circus/atriumRoster needs an Atrium with the screen extensions registry (v0.1.0 or later): Composer refuses an older tagged Atrium. Without Atrium the atrium.roster.* routes don't exist, so route() calls to them throw.
Roster stands on refactor-circus/keystone, the shared runtime of the Refactor Circus package suite, which Composer installs with it. Roster's Action events implement Keystone's ActionStartingEvent and ActionFinishedEvent contracts, so one listener hears every package of the suite.
Roster manages whatever model roster.users.model points at (default App\Models\User).
1. Your model with the trait (recommended). This gives typed helpers:
use RefactorCircus\Roster\Domains\User\Concerns\HasRoster;
class User extends Authenticatable
{
use HasRoster;
}
$user->roster(); // the Profile, created on first access
$user->rosterStatus(); // a case of the roster.statuses.users enum: UserStatus::Active | Pending | Suspended | Deactivated by default
$user->isRosterActive();2. Your model, untouched. Without the trait, Roster registers the rosterProfile relation on the configured model at boot. Everything works the same; use app(RefactorCircus\Roster\Support\Users::class)->profile($user) / ->status($user) in place of the helpers.
3. Roster's model. For apps without a users table, point roster.users.model and your auth provider at RefactorCircus\Roster\Domains\User\Models\UserModel, then publish its migration:
php artisan vendor:publish --tag="roster-users-migration"If your users table names its columns differently, map them:
'columns' => ['name' => 'full_name', 'email' => 'email_address', 'password' => 'secret'],Roster finds users by email ignoring case. It looks the address up as given and lowercased first, which your email column's index serves; only an address stored with other casing falls back to a case-insensitive comparison. On PostgreSQL that comparison is lower(email) = ?; publish the optional migration adding the matching expression index to your users table (it does nothing on other databases):
php artisan vendor:publish --tag="roster-email-index-migration"Every operation is an Action in its domain's Actions namespace (RefactorCircus\Roster\Domains\{Domain}\Actions, e.g. Domains\User\Actions\CreateUserAction). An Action takes its input as a typed, immutable Data object from the domain's Data namespace, named after it (CreateUserAction takes Domains\User\Data\CreateUserData), never as an array.
use RefactorCircus\Roster\Domains\User\Actions\{CreateUserAction, SuspendUserAction};
use RefactorCircus\Roster\Domains\User\Data\{CreateUserData, SuspendUserData};
$user = app(CreateUserAction::class)->execute(new CreateUserData(
email: 'ada@example.com',
name: 'Ada Lovelace',
displayName: 'Ada', // profile fields are accepted too
));
app(SuspendUserAction::class)->execute($user, new SuspendUserData(reason: 'Chargeback'), actor: auth()->user());Untrusted input validates itself. XData::from($input) checks the input against the Data's rules() (throwing a ValidationException) and fills each typed field from its snake_case key, casting enums, numbers and booleans. Atrium and the signed pages build their Data this way. The API and MCP requests validate once, with the Data's rules among their own (XData::rules()), and build with XData::fromValidated($request->validated()), so every error comes back in one response; every surface validates with the same rules. new XData(...) is for values your own code vouches for, and is not validated.
$user = app(CreateUserAction::class)->execute(CreateUserData::from($request->all()));
UpdateUserData::rules($user); // the rules, for your own forms; some take context like the user being updatedOptional fields of an update default to RefactorCircus\Keystone\Data\Missing, so a field you leave out is left alone and a field set to null is cleared: new UpdateUserData(name: 'Ada King') changes the name only. Ask with $data->has('email').
| Action | Does |
|---|---|
ListUsersAction |
Paginated list; search (name, email, display name), status, per_page |
ShowUserAction |
One user with profile |
CreateUserAction |
User + profile in one transaction; random password when none is given |
UpdateUserAction |
Name, email, password |
DeleteUserAction |
Deletes the user; the profile too, unless the model soft-deletes |
UpdateProfileAction |
Profile fields; creates the profile if missing |
SuspendUserAction / DeactivateUserAction |
Optional reason |
ApproveUserAction / RejectUserAction |
Accept or turn down an account awaiting approval (see below) |
ReactivateUserAction |
Back to active |
Business-rule failures, such as suspending yourself or suspending a user who is already suspended, throw a field-keyed ValidationException.
Every Action dispatches an event before and after it runs (RefactorCircus\Roster\Domains\{Domain}\Events\*ActionEvent): UserSuspendingActionEvent with the input, then UserSuspendedActionEvent with the result. The first implements Keystone's ActionStartingEvent, the second ActionFinishedEvent, so one listener hears every action of the suite. Finished events wait for the surrounding transaction to commit, and an Action that throws fires none.
The background steps of a CSV import or export announce themselves the same way: ImportValidatingActionEvent / ImportValidatedActionEvent while the file is checked, ImportRowApplyingActionEvent / ImportRowAppliedActionEvent around each confirmed row (as the person who confirmed it), ExportBuildingActionEvent / ExportBuiltActionEvent while the file is written, and TransferFinishingActionEvent / TransferFinishedActionEvent when the transfer completes, is cancelled or expires.
use Illuminate\Support\Facades\Event;
use RefactorCircus\Keystone\Contracts\ActionFinishedEvent;
use RefactorCircus\Roster\Domains\User\Events\UserSuspendedActionEvent;
Event::listen(UserSuspendedActionEvent::class, fn ($event) => /* ... */);
Event::listen(ActionFinishedEvent::class, fn ($event) => /* every action */);Every model dispatches an event for each Eloquent hook: retrieved, creating, created, updating, updated, saving, saved, deleting, deleted and replicating, plus restoring, restored, trashed, forceDeleting and forceDeleted on the soft-deleting OrganizationModel and UserModel. Each is a class named after the model and hook - TeamModel fires RefactorCircus\Roster\Domains\Team\Events\TeamCreatingEvent - holding the record ($event->team). They implement Keystone's ModelLifecycleEvent (model(), hook()), so Event::listen(ModelLifecycleEvent::class, ...) hears every model of the suite. As with Eloquent, a creating, updating, saving or deleting listener that returns false stops the write.
An organization is the tenant. Users join it as members, and teams group members inside it. A user can belong to many organizations. Organizations and teams are identified by slug; team slugs are unique within their organization.
use RefactorCircus\Roster\Domains\Organization\Actions\{AddMemberAction, CreateOrganizationAction};
use RefactorCircus\Roster\Domains\Organization\Data\{AddMemberData, CreateOrganizationData};
use RefactorCircus\Roster\Domains\Team\Actions\{AddTeamMemberAction, CreateTeamAction};
use RefactorCircus\Roster\Domains\Team\Data\{AddTeamMemberData, CreateTeamData};
$acme = app(CreateOrganizationAction::class)->execute(new CreateOrganizationData(name: 'Acme'), owner: $user);
app(AddMemberAction::class)->execute($acme, new AddMemberData(user: $ada->getRouteKey()));
$ops = app(CreateTeamAction::class)->execute($acme, new CreateTeamData(name: 'Ops'));
app(AddTeamMemberAction::class)->execute($ops, new AddTeamMemberData(user: $ada)); // must be an org member- An organization has at most one owner. The owner can't be removed, and
TransferOwnershipActionhands ownership to another member. A user who owns a shared organization can't be deleted until they transfer it. - An organization may have no owner (leave out
owner), as organizations synced from an ERP usually start. Atrium flags it, andTransferOwnershipActionmakes a member the owner. Personal organizations always have one. - Removing a member also removes their team seats.
- Personal organizations: set
roster.organizations.personaltotrueand every user created through Roster gets one. It is deleted with its owner and can't be deleted or transferred on its own.
app(SwitchContextAction::class)->execute($user, new SwitchContextData(organization: 'acme', team: 'ops'));
$user->currentOrganization(); // falls back to the first organization joined
$user->currentTeam(); // null unless set and the user still holds a seatWithout the trait, use app(RefactorCircus\Roster\Roster::class)->organization($user) and ->team($user). Add the roster.organization middleware to routes that need a tenant; users who belong to no organization get a 403.
CreateInvitationAction invites an email address, optionally onto some teams, and emails a link. The address doesn't need an account yet.
- The link opens Roster's page at
/roster/invitation/{token}. The page is signed, expires with the invitation, and sits behindroster.invitations.middleware(default['web', 'auth']). Guests go through your login or registration first. With Atrium installed it is an Atrium page (theroster.invitationscreen, which other packages can extend); without it, a plain HTML page with the same forms. - Only a signed-in user whose email matches the invitation can accept or decline it, so a forwarded link is useless to anyone else.
- After answering, the user is redirected to
roster.invitations.redirect. - To use your own page instead, set
roster.invitations.accept_url(e.g.https://app.test/join/{token}) and callAcceptInvitationAction/DeclineInvitationActionfrom it. - Only a hash of the token is stored.
Give an organization domains and turn on auto_join. Users then join automatically when they verify their email (Laravel's Verified event), or when created already verified. Only user models implementing MustVerifyEmail ever count as verified, because an unverified address on acme.com proves nothing. A domain can belong to one organization only.
Permissions are named abilities (roster.users.update, or your own invoices.edit). Roles bundle permissions and are assigned globally, in an organization, or on a team. Both live in the database and can be edited from Atrium, the API or MCP.
use RefactorCircus\Roster\Domains\Permission\Actions\CreatePermissionAction;
use RefactorCircus\Roster\Domains\Permission\Data\CreatePermissionData;
use RefactorCircus\Roster\Domains\Role\Actions\{AssignRoleAction, CreateRoleAction};
use RefactorCircus\Roster\Domains\Role\Data\{AssignRoleData, CreateRoleData};
use RefactorCircus\Roster\Domains\Role\Enums\RoleScope;
app(CreatePermissionAction::class)->execute(new CreatePermissionData(name: 'invoices.edit'));
$billing = app(CreateRoleAction::class)->execute(new CreateRoleData(
name: 'Billing',
scope: RoleScope::Organization, // Global | Organization | Team
permissions: ['invoices.edit'],
));
app(AssignRoleAction::class)->execute($user, new AssignRoleData(role: $billing->id, organization: 'acme'));
$user->can('invoices.edit', $acme); // true
$user->can('invoices.edit'); // checks the user's current organization/teamHow a check resolves:
- Scopes add up. A user's permissions in an organization are their global roles plus their roles in that organization. On a team, they also include the team's roles.
- Owners. An organization's owner holds every permission inside it, except the global-only ones (
roster.users.*,roster.organizations.create,roster.organizations.sync,atrium.*). - Super-admins pass every Gate check, Roster's or your app's.
- Gate integration.
Gate::beforeanswers any ability that is a known permission. When the user lacks it, Roster returnsnullrather thanfalse, so your own gates and policies still run. - Shared and custom roles. A role without an organization is shared by every organization. With
organization, it is that organization's own. - No escalation. Actors can only grant permissions they hold in that scope. Only super-admins can assign or revoke super roles.
- Remembered per request. The permission names and each user's role assignments load once per request; Roster's own actions forget what they change (one user's answers for a change to that user, everything for a change to roles or permissions). Asking with a record (
$user->can('update', $membership)) finds its organization or team once per request; eager-loadorganization/teamon a list you check record by record and there is no lookup at all.
To keep the permission names and role assignments between requests too, set a cache lifetime (off by default):
'permission_cache' => [
'ttl' => 300, // seconds; 0 keeps them per request only
'store' => null, // the cache store; null for the default
],Roster's Actions and its role, assignment and permission models clear the cache. After writing those tables some other way, call app(\RefactorCircus\Roster\Domains\Permission\Services\Permissions::class)->forgetCache().
Built-in roles (re-sync with php artisan roster:sync-permissions after upgrading; existing edits are kept):
| Role | Scope | Grants |
|---|---|---|
super-admin |
global | everything |
admin |
organization | every organization-scoped roster.* permission, including roster.audit.view |
member |
organization | roster.organizations.view, roster.members.view, roster.teams.view; given to every new member (roster.roles.default_member) |
lead |
team | roster.teams.view, roster.teams.manage |
php artisan roster:grant-super-admin admin@example.comAlternatively, list emails in roster.super_admins. Listed emails only count once verified, on user models implementing MustVerifyEmail.
With roster.authorization on (the default), every API route, MCP tool and Atrium screen needs a signed-in user holding the matching roster.* permission. Guests get a 401 and other users a 403. Users can always view themselves and edit their own profile and current context.
If your app hasn't defined Atrium's viewAtrium gate, Roster defines it as the atrium.view permission.
Each Roster model has a policy. The core models' policies are registered with the Gate from roster.policies; package resources register their own policies (see Extending Roster), and an entry for one of their models in roster.policies still wins. Point a model at a class of your own to change who may do what:
'policies' => [
OrganizationModel::class => App\Policies\OrganizationPolicy::class,
// ...
],use Illuminate\Database\Eloquent\Model;
use RefactorCircus\Roster\Domains\Organization\Policies\OrganizationPolicy as RosterOrganizationPolicy;
class OrganizationPolicy extends RosterOrganizationPolicy
{
// Roster's API, MCP tools and Atrium screens pass the organization or team
// the call is about ($subject), and the user it is about when everyone may
// do it to themselves ($self). Your own checks pass the record.
public function delete(?Model $user, ?Model $subject = null, ?Model $self = null): bool
{
return $user?->email === 'founder@example.com';
}
}Roster's own checks ask them. On every surface, permission roster.{resource}.{verb} asks the policy of the resource's model, by the camel-cased verb: roster.organizations.update asks update() on OrganizationModel's policy, roster.users.manage-status asks manageStatus() on UserModel's. The core resources are users (UserModel, whatever your user model is), organizations, members (MembershipModel), teams, invitations and roles (which covers permissions). Other packages register their own resources the same way (see Extending Roster). The other models' policies (profiles, domains, links, seats, assignments, permissions, impersonations, transfers and their rows) answer your own checks: $user->can('manage', $domain).
The bundled policies answer with Roster's permissions, so nothing changes until you swap one. Since checks now go through the Gate, your app's Gate::before callbacks apply to them too. Some things stay with Roster whatever a policy says: permissions blocked while impersonating are refused first, roster.audit.view has no model and is checked directly, and the organization-limited lists above still work out the caller's organizations from their roles. Remove a model's entry to check its resource by Roster's permissions alone.
Organization admins. A permission held only in some organizations (through an organization role, or by owning the organization) still opens the lists of organizations, roles, impersonations and transfers. Asked without an organization, those lists hold only what falls within the user's organizations: their organizations, the shared roles plus those organizations' own, and so on. On every surface: Atrium, the API and MCP. Asking for another organization is still refused. In Atrium, the matching navigation items appear for them too; Users and Permissions stay global, as does the users search.
Roster keeps no audit log of its own and records nothing itself. Install refactor-circus/keen, the audit log of the Refactor Circus suite, and Keen records every change Roster makes: users, profiles and status, organizations, members, teams, invitations, roles, permissions and assignments. Reads are not recorded. Without Keen there is no audit history anywhere in Roster.
composer require refactor-circus/keen
php artisan migrateTo keep Roster out of the audit log while Keen is installed, set roster.audit.enabled to false: Keen records nothing of Roster's, and Roster offers no history. Roster::auditing() says whether Roster audits right now.
While it does, Roster teaches Keen about its records through refactor-circus/keystone's AuditHooks:
- Labels: users by name or email, organizations, teams and roles by name, invitations by email, role assignments by role, transfers by type.
- Field changes include profile fields (
profile.status), a role's permissions, an organization's domains, and the role, organization and team of an assignment. - Subject: an entry about a role assignment or an impersonation is about the user; otherwise about the event's
user, when it has one. - Scope: the organization the change belongs to (a user's current organization for changes to the user alone), so Keen can be read per organization.
- Context:
impersonatorwhile someone is impersonating, andtransferfor a change made by a CSV import. Other packages add their own (see Audit context). - Surfaces: the signed invitation and impersonation pages are recorded as
web. - Redaction: the users table's password column, on top of Keen's own list.
While Roster audits:
- With Atrium installed, Keen adds each record's history to Roster's screens through Atrium's screen extensions (see Screen extensions); Roster no longer renders history itself. Keen's own Audit log section reads everything.
GET /roster/historyandlist-roster-history-toolserve Roster's history, to holders of the globalroster.audit.view.- If your app hasn't defined the
viewAuditLogGate ability that Keen and every package's history ask, Roster defines it as the globalroster.audit.viewpermission. Define your own to take over.
Otherwise the pages show no history, the route answers 404, and the tool is not offered (to MCP clients or to Cortex).
Record your app's own events with Keen directly: Keen::record('invoice.paid')->on($invoice)->in($organization)->save();.
Without Guardian, organizations that enforce SSO accept password sign-in. Roster no longer ships single sign-on or SCIM provisioning, and adds no guard of its own: refactor-circus/guardian adds OpenID Connect, SAML 2.0 and Microsoft Entra ID sign-in, SSO enforcement and a SCIM 2.0 endpoint to Roster's organizations, through Roster's extension seams. Install it in the same deploy as this Roster version:
composer require refactor-circus/guardianUpgrading from a Roster that still had them (the CHANGELOG has the full steps):
- Install Guardian in the same deploy.
- Before running any migrate command, delete your published
create_roster_sso_tablesandcreate_roster_scim_tablesmigrations and never roll them back (theirdown()drops the tables), and remove the SSO/SCIM keys from published copies of the two index migrations. - Publish and run Guardian's migrations, then
php artisan roster:sync-permissions. Guardian renames theroster_sso_*/roster_scim_*tables and theroster.sso.*/roster.scim.*role grants to its ownguardian_*/guardian.*names. If you installed Guardian before this Roster version, runphp artisan guardian:upgrade-from-rosterafter upgrading Roster to finish the rename. - Move published
roster.sso/roster.scimconfig to Guardian's keys, and check its SCIM prefix (Roster's wasscim/v2). - Use Guardian's class, route and permission names in place of Roster's old ones.
- Replace
NotSsoEnforcedin your login validation withRefactorCircus\Roster\Support\Rules\NoExternalSignIn.
Without Guardian nothing is deleted: the tables, their rows and the three permissions stay where they are, SSO sign-in and the SCIM endpoints answer 404, roster:sync-permissions reports the permissions as unregistered, ?tab=sso and ?tab=scim open the members tab, and members provisioned through SCIM show their stored source, scim.
When your organizations live in another system of record, such as an ERP or a CRM, Roster can create and update them from those records. It remembers each organization's id and account number in every system it comes from.
use RefactorCircus\Roster\Domains\Organization\Actions\SyncOrganizationAction;
use RefactorCircus\Roster\Domains\Organization\Data\SyncOrganizationData;
$result = app(SyncOrganizationAction::class)->execute(SyncOrganizationData::from([
'source' => 'erp', // which system, lower case
'external_id' => 'C-100', // its id there
'account_number' => 'A-42',
'name' => 'Initech',
'domains' => ['initech.test'],
]));
$result->outcome; // 'created', 'updated' or 'unchanged'
$result->organization->links; // [OrganizationLink{source: erp, external_id: C-100, account_number: A-42}]- Matching is by
source+external_id. An unknown record creates an organization. To link an existing organization on its first sync, passorganization(its slug) instead. - Only the fields you send are written:
name,slug,domains,auto_join,status,status_reasonandaccount_number. Anything left out stays as it is. Local edits are allowed, and the next sync overwrites them. - Owners. A new organization has no owner unless the record names one (
owner, a user key). An owner is only applied to an organization that doesn't have one yet; sync never replaces an existing owner. - Several systems: an organization can be linked to one record per source, for example
erpandcrm. Manage links by hand withLinkOrganizationAction/UnlinkOrganizationAction, or on the organization's Settings tab in Atrium. - Finding them:
ListOrganizationsActionandGET /roster/organizationstakesource,external_idandaccount_numberfilters. - Exporting: the
export_organizationsCSV uses the same columns as the import, so you can export, edit and re-import. Atrium's Organizations page links to Imports & exports. - In bulk:
SyncOrganizationsAction(POST /roster/organizations/sync) takes up toroster.organizations.sync_batch(500) records. Each record succeeds or fails on its own, and the response listscreated/updated/unchanged/error(with messages) per record, in order. For files, use theimport_organizationsCSV import. - Permission: the sync Actions and the CSV import need the global
roster.organizations.syncpermission. Give an integration user just that, plusroster.organizations.viewif it needs to look organizations up. Linking and unlinking by hand needroster.organizations.updatein the organization. - Audit: with Keen installed, each sync records
organization.syncedwith the source, id and outcome, next to the usualorganization.created/organization.updatedentries. A batch also recordsorganizations.syncedwith its counts.
Holders of roster.users.impersonate can temporarily act as another user to see what they see. Nobody gets it by default, so grant it deliberately: globally to impersonate anyone, or in an organization to impersonate its members.
use RefactorCircus\Roster\Domains\Impersonation\Actions\StartImpersonationAction;
use RefactorCircus\Roster\Domains\Impersonation\Data\StartImpersonationData;
$started = app(StartImpersonationAction::class)->execute($user, new StartImpersonationData(reason: 'Ticket #4521'), actor: $admin);
return redirect($started->url); // a one-time link, valid for a few minutesIn Atrium, use the Impersonate card on a user's page. Over the API and MCP, the link is returned once for the operator to open.
Safety rails
- The link only works in the impersonator's own browser (signed in as them), works once, and expires after
link_minutes(5). Only its hash is stored. - Refused targets: yourself, inactive users, super-admins (unless you are one), and anyone holding a permission you lack. You can't impersonate while already impersonating.
- A reason is required, and the session ends on its own after
ttl_minutes(30): on the impersonator's next request, or, if they never come back, whenphp artisan roster:end-expired-impersonationsruns. Schedule it (every five minutes, say) so every expired session and unused link is ended on the record. - Blocked while impersonating: the abilities in
roster.impersonation.blockedare refused, even for super-admins. This works through Roster's checks and Laravel's Gate, so your own abilities can be listed too (wildcards likebilling.*). The impersonated account's email and password can't be changed. - Ending it: a global holder can end anyone's impersonation (Atrium → Impersonations). The browser switches back on its next request.
The banner. Show it in your own layout:
@include('roster::impersonation-banner')It names who you're acting as and who you really are, shows the time left, and has a "Return to my account" button. With Atrium installed it is Atrium's banner in standalone mode; without it, a plain banner. Both are styled inline, so they need nothing from Atrium's stylesheet on your own pages. Pass ['bannerClass' => '...'] to add classes. Roster's Atrium pages already include it. (It was the <x-roster::impersonation-banner /> component before Roster dropped its component namespace.)
Audit. With Keen installed, everything done while impersonating is recorded as the impersonated user, with context.impersonator naming the real person. Starting, entering and ending each get their own entry.
The roster.impersonation middleware, which ends expired or revoked sessions, is added to the web group automatically. Set roster.impersonation.middleware_group to null to add it yourself.
Bulk-add members, users and teams from a CSV, and export members, users or organizations. Imports and exports run in the background as refactor-circus/impex flows, so Impex is needed for this feature:
composer require refactor-circus/impex
php artisan vendor:publish --tag="impex-migrations"
php artisan migrateRun a queue worker, and schedule Laravel's scheduler (Impex's impex:tick expires unconfirmed imports) and roster:prune-transfers. Without Impex, the transfer Actions throw a TransfersUnavailableException that names the missing package, and the Atrium page shows the same setup note.
Imports are previewed, then confirmed. Uploading checks every row against the current data and stores a preview. Nothing changes until someone confirms it:
| Row outcome | Meaning |
|---|---|
create |
A new account (or team) is created |
link |
An existing account on the organization's domains joins |
invite |
The email is outside the organization's domains, so an invitation is sent |
update |
Adds teams, a role or team members; nothing is ever removed |
skip |
Already as the row describes |
error |
The reason is shown, and the row is left out |
The preview's rows come back a page at a time (rows_page, 100 per page) from GET /roster/transfers/{transfer} and show-transfer-tool, and are kept in roster_transfer_rows. Confirming applies the rows one by one, as the person who confirmed. Their permissions are checked again, and each row is checked again against the data at that moment. Errors are reported per row; the rest still apply. A retried row is never applied twice. An import not confirmed within roster.transfers.confirm_within_hours (24) expires.
| Type | Columns (first row is the header) | Permission |
|---|---|---|
import_members |
email required; name, display_name, teams, role |
roster.members.manage in the organization; invite rows also need roster.invitations.manage |
import_users |
email required; name, display_name |
roster.users.create |
import_teams |
name required; slug, members (emails of existing members) |
roster.teams.manage in the organization |
import_organizations |
source, external_id required; name (required for new ones), account_number, slug, domains, owner (an email). Blank cells leave a field as it is |
roster.organizations.sync |
export_members |
email, name, display name, status, teams, roles, owner, source, joined | roster.members.view in the organization |
export_users |
id, email, name, display name, status, created | roster.users.view |
export_organizations |
the import_organizations columns, one row per external record (unlinked organizations get one row with no source), so an edited file imports straight back; optional filters.external_source keeps one system's records |
roster.organizations.view |
Templates. Every import type has a CSV template: the header row, plus commented example rows. Rows whose first cell starts with # are ignored, so an untouched template imports nothing; it's refused as having no rows. Download them in Atrium (the template picker on Imports & exports), from GET /roster/imports/templates/{type}, or with show-import-template-tool. Any signed-in user may download them, since they hold no data. To change them (for example to match your own wording or examples), publish them:
php artisan vendor:publish --tag="roster-import-templates"The published copies in resources/roster/import-templates/{type}.csv are served instead of Roster's own.
Separate lists (teams, members, domains) with ;, , or |. Teams are matched by slug or name, and roles by slug. You can only assign roles whose permissions you hold.
use RefactorCircus\Roster\Domains\Transfer\Actions\ConfirmImportAction;
use RefactorCircus\Roster\Domains\Transfer\Actions\StartExportAction;
use RefactorCircus\Roster\Domains\Transfer\Actions\StartImportAction;
use RefactorCircus\Roster\Domains\Transfer\Data\{StartExportData, StartImportData};
use RefactorCircus\Roster\Domains\Transfer\Enums\TransferType;
$import = app(StartImportAction::class)->execute(new StartImportData(
type: TransferType::ImportMembers,
organization: 'acme',
file: $request->file('csv'), // or content: $csvText
), $request->user());
$import->rows(); // [['line' => 2, 'action' => 'invite', 'reasons' => [...]], ...]
app(ConfirmImportAction::class)->execute($import, $request->user());
$export = app(StartExportAction::class)->execute(new StartExportData(type: TransferType::ExportMembers, organization: 'acme'), $request->user());Safety
- No passwords. A file with a
passwordcolumn is refused. New accounts get a random password; people reset it or sign in another way their app offers. - Accounts outside the organization's domains are never claimed. Those rows become invitations.
- Limits:
max_bytes(5 MB) andmax_rows(10,000). UTF-8 with or without a BOM is accepted. - Formula injection: exported cells starting with
=,+,-,@, a tab or a carriage return get a leading', so spreadsheets show them as text. - Files live on
roster.transfers.disk(keep it private) underroster/transfers/{id}. They are only served through Roster's authorized download route, to whoever started the transfer or holds its permission in scope. MCP gets a signed link valid for 15 minutes.roster:prune-transfersdeletes files older thanretention_days(7).
Audit. Every row is applied as the person who confirmed, so with Keen installed it is recorded as theirs, with surface import and context.transfer naming the import. Starting, confirming, cancelling and finishing each have their own entry.
Deleting a user or an organization is recoverable. It goes to Deleted (Atrium's lists have a Show: Current / Deleted filter), and can be restored with everything it had until it's deleted permanently.
-
Users need Laravel's
SoftDeleteson the user model. Roster's bundledRefactorCircus\Roster\Domains\User\Models\UserModelhas it; add it to your own model and adeleted_atcolumn ($table->softDeletes()):use Illuminate\Database\Eloquent\SoftDeletes; class User extends Authenticatable { use HasRoster, SoftDeletes; }
Laravel then hides deleted users everywhere, sign-in included. Their profile, memberships, team seats, roles and personal organization are kept for a restore. A model without the trait is deleted permanently, as before, and the warning says so.
-
Organizations always soft-delete. A deleted organization is switched off: its pages and API 404, its members lose access, and its domain auto-join stops. Its slug and domains stay reserved, so a restore always works.
-
Restore with
RestoreUserAction/RestoreOrganizationAction,POST /roster/users/{user}/restore/POST /roster/organizations/{organization}/restore, the MCP restore tools, or the Restore buttons in Atrium. It needs the same permission as deleting. -
Delete permanently with
PurgeUserAction/PurgeOrganizationAction,DELETE …/purge, the MCP purge tools, or the deleted record's Danger zone in Atrium. Only deleted records can be purged, and it needsroster.users.purge/roster.organizations.purge. -
Organizations are purged in the background, since a large one takes all its teams, members, invitations, roles and connections with it: the API, MCP and Atrium check the request at once (a refusal answers right away), then queue a
PurgeOrganizationJoband answer202 Accepted, so the organization disappears shortly after. CallPurgeOrganizationAction::queue($organization)to do the same, orexecute()to purge in place. Run a queue worker. An organization restored before the job runs is kept. -
Automatically: schedule
php artisan roster:purge-deletedto permanently delete records deleted more thanroster.deletes.retention_daysdays ago (organizations are queued, one job each). The default,null, keeps deleted records forever;--days=Noverrides it for one run.
New accounts can wait for an approver instead of becoming active straight away. They then have the status pending ("Awaiting approval"). Who starts pending depends on how the account was made:
| Created by | Starting status |
|---|---|
The app's own registration (Laravel's Registered event, which Breeze, Fortify and Jetstream fire) |
roster.users.registration_status: active (default) or pending |
An admin: CreateUserAction, Atrium's create form, the API or MCP |
Their choice, through the status input (active by default) |
| A package that provisions accounts for an organization from outside (refactor-circus/guardian, for one) | That organization's provisioned_status setting (active by default), on its Settings tab |
CSV imports create active users.
- Approving and rejecting:
ApproveUserActionmakes a pending account active.RejectUserActiondeactivates it with an optionalreason. The account is kept and can be reactivated later, and the email stays taken.- Both need the global
roster.users.approvepermission. Organization admins don't get it, because accepting an account is a site decision. - In Atrium, a pending user's page shows Approve and Reject buttons, and the Users list filters by "Awaiting approval".
- While pending:
roster.activeanswers 403 with "Your account is awaiting approval".- Reactivating a pending account is refused; approve it instead.
- Emails, each switchable in
roster.users.approvals:notify_approverstells everyone withroster.users.approve(super-admins included) when someone is waiting.notify_usertells people when they're approved or rejected.
Route::middleware(['auth', 'roster.active'])->group(...);Suspended and deactivated users get a 403, and so do users awaiting approval (with their own message). A user with no profile row is active. With your own status enum, every status whose allowsAccess() is false is refused.
Users, organizations and teams each have a status (with status_reason and status_changed_at). Which statuses exist is up to you: each is a string-backed enum named under roster.statuses.
| Key | Default enum | Contract | Cases |
|---|---|---|---|
users |
Domains\User\Enums\UserStatus |
RefactorCircus\Roster\Contracts\AccountStatus |
active, pending, suspended, deactivated |
organizations |
Domains\Organization\Enums\OrganizationStatus |
RefactorCircus\Roster\Contracts\Status |
active, inactive |
teams |
Domains\Team\Enums\TeamStatus |
RefactorCircus\Roster\Contracts\Status |
active, inactive |
Status asks for a label(), an Atrium badge() variant and the default() new records start with. AccountStatus adds the cases Roster's flows move users between (active(), pending(), suspended(), deactivated()) and allowsAccess(), so an enum can rename those cases or add its own, such as a trial that lets users in:
use RefactorCircus\Roster\Contracts\Status;
enum CustomerStatus: string implements Status
{
case Active = 'active';
case OnHold = 'on_hold';
case Blocked = 'blocked';
public static function default(): static { return self::Active; }
public function label(): string { return __('customers.status.'.$this->value); }
public function badge(): string { return $this === self::Active ? 'success' : 'warning'; }
}
// config/roster.php
'statuses' => ['organizations' => CustomerStatus::class, /* ... */],- Organization and team statuses are data only. Roster stores, shows and filters by them, but grants and refuses nothing by them; check them in your own middleware or policies if they should block anything.
- Setting them: pass
status(and optionallystatus_reason) toCreateOrganizationData,UpdateOrganizationData,SyncOrganizationData,CreateTeamDataandUpdateTeamData, the matching API routes and MCP tools, or the Settings forms in Atrium. A changed status stampsstatus_changed_at; the reason is kept until you send another. - Finding them:
ListOrganizationsAction/ListTeamsAction(and their routes and tools) take astatusfilter. - Code reads the configured enum through
RefactorCircus\Roster\Support\Statuses:Statuses::users()::pending(),Statuses::organization('inactive'). - Changing enums only changes what new values may be. Rows keep the value they hold, and reading a row whose value is no longer a case fails, so move rows off a status before removing it. New organizations and teams default to the enum's
default(); the migration gives existing rows the default of the enum configured when it runs.
Security: both are off by default. Every route and tool checks the caller's Roster permissions, but that needs an authenticated user, so add authentication middleware before enabling them.
'routes' => ['enabled' => true, 'prefix' => 'roster', 'middleware' => ['api', 'auth:sanctum']],
'mcp' => ['web' => ['enabled' => true, 'route' => 'mcp/roster', 'middleware' => ['api', 'auth:sanctum']]],| Method | URI | Name |
|---|---|---|
| GET | /roster/users |
roster.users.index |
| POST | /roster/users |
roster.users.store |
| GET | /roster/users/{user} |
roster.users.show |
| PATCH | /roster/users/{user} |
roster.users.update |
| DELETE | /roster/users/{user} |
roster.users.destroy |
| PATCH | /roster/users/{user}/profile |
roster.users.profile.update |
| POST | /roster/users/{user}/suspend |
roster.users.suspend |
| POST | /roster/users/{user}/deactivate |
roster.users.deactivate |
| POST | /roster/users/{user}/reactivate |
roster.users.reactivate |
| POST | /roster/users/{user}/approve |
roster.users.approve |
| POST | /roster/users/{user}/restore |
roster.users.restore |
| DELETE | /roster/users/{user}/purge |
roster.users.purge (deleted users only) |
| POST | /roster/users/{user}/reject |
roster.users.reject |
| PUT | /roster/users/{user}/context |
roster.users.context.update |
| POST | /roster/users/{user}/domain-join |
roster.users.domain-join |
| GET, POST | /roster/organizations |
roster.organizations.index, .store |
| GET, PATCH, DELETE | /roster/organizations/{organization} |
roster.organizations.show, .update, .destroy |
| POST | /roster/organizations/{organization}/transfer |
roster.organizations.transfer |
| POST | /roster/organizations/{organization}/restore |
roster.organizations.restore |
| DELETE | /roster/organizations/{organization}/purge |
roster.organizations.purge (deleted organizations only; 202, purged by a queued job) |
| PUT | /roster/organizations/external/{source}/{externalId} |
roster.organizations.sync (upsert; 201 when created) |
| POST | /roster/organizations/sync |
roster.organizations.sync-many ({records: [...]}) |
| PUT, DELETE | /roster/organizations/{organization}/links/{source} |
roster.organizations.links.update, .destroy |
| GET, POST | /roster/organizations/{organization}/members |
roster.organizations.members.index, .store |
| DELETE | /roster/organizations/{organization}/members/{user} |
roster.organizations.members.destroy |
| GET, POST | /roster/organizations/{organization}/teams |
roster.organizations.teams.index, .store |
| GET, PATCH, DELETE | /roster/organizations/{organization}/teams/{team} |
roster.organizations.teams.show, .update, .destroy |
| POST | /roster/organizations/{organization}/teams/{team}/members |
roster.organizations.teams.members.store |
| DELETE | /roster/organizations/{organization}/teams/{team}/members/{user} |
roster.organizations.teams.members.destroy |
| GET, POST | /roster/organizations/{organization}/invitations |
roster.organizations.invitations.index, .store |
| DELETE | /roster/organizations/{organization}/invitations/{invitation} |
roster.organizations.invitations.revoke |
| POST | /roster/invitations/{token}/accept |
roster.invitations.accept (as the authenticated user) |
| POST | /roster/invitations/{token}/decline |
roster.invitations.decline (as the authenticated user) |
| GET, POST | /roster/permissions |
roster.permissions.index, .store |
| PATCH, DELETE | /roster/permissions/{permission} |
roster.permissions.update, .destroy |
| GET, POST | /roster/roles |
roster.roles.index, .store |
| GET, PATCH, DELETE | /roster/roles/{role} |
roster.roles.show, .update, .destroy |
| GET, POST | /roster/users/{user}/roles |
roster.users.roles.index, .store |
| DELETE | /roster/users/{user}/roles/{assignment} |
roster.users.roles.destroy |
| GET | /roster/users/{user}/permissions |
roster.users.permissions |
| POST | /roster/users/{user}/impersonate |
roster.users.impersonate |
| GET | /roster/impersonations |
roster.impersonations.index |
| DELETE | /roster/impersonations/{impersonation} |
roster.impersonations.destroy |
| GET | /roster/history |
roster.history.index (the shared refactor-circus/keen history; 404 until it is installed) |
| POST | /roster/imports |
roster.imports.store (multipart file, or content) |
| GET | /roster/imports/templates/{type} |
roster.imports.templates.show (CSV template; any signed-in user) |
| POST | /roster/imports/{transfer}/confirm |
roster.imports.confirm |
| POST | /roster/exports |
roster.exports.store |
| GET | /roster/transfers |
roster.transfers.index |
| GET, DELETE | /roster/transfers/{transfer} |
roster.transfers.show, .destroy (cancel) |
| GET | /roster/transfers/{transfer}/download |
roster.transfers.download |
| GET | /roster/transfer-files/{transfer} |
roster.transfers.file (signed links for MCP; always on) |
GET .../members takes team (a team's slug) to list only that team's members. A team's own response (GET .../teams/{team}) carries at most its first 100 members, with the full members_count; page through the rest with members?team=.
{user} is the user model's route key; {organization} and {team} are slugs; {role}, {assignment}, {invitation} and {entry} are ids; {permission} is the permission name. Responses use a data envelope. The MCP server offers one tool per Action, and each tool returns the same payload as the HTTP API as structured content: the record under data, a list's page under meta (current_page, last_page, per_page, total), and extras such as a sync's outcome beside them. Every tool that answers this way declares an output schema, so an agent knows each field, its type and its allowed values before calling it. Deletes and the import template answer with text.
MCP tools (all behind Laravel MCP's tool search):
| Area | Tools |
|---|---|
| Users | list-users-tool, show-user-tool, create-user-tool, update-user-tool, delete-user-tool, update-profile-tool, suspend-user-tool, deactivate-user-tool, reactivate-user-tool, approve-user-tool, reject-user-tool, restore-user-tool, purge-user-tool, switch-context-tool, join-by-domain-tool |
| Organizations | list-organizations-tool, show-organization-tool, create-organization-tool, update-organization-tool, delete-organization-tool, restore-organization-tool, purge-organization-tool, transfer-ownership-tool, list-members-tool, add-member-tool, remove-member-tool, sync-organization-tool, sync-organizations-tool, link-organization-tool, unlink-organization-tool |
| Teams | list-teams-tool, show-team-tool, create-team-tool, update-team-tool, delete-team-tool, add-team-member-tool, remove-team-member-tool |
| Invitations | list-invitations-tool, create-invitation-tool, revoke-invitation-tool, accept-invitation-tool, decline-invitation-tool |
| Impersonation | start-impersonation-tool, list-impersonations-tool, stop-impersonation-tool |
| History | list-roster-history-tool (reads refactor-circus/keen) |
| CSV import and export | show-import-template-tool, start-import-tool, confirm-import-tool, start-export-tool, list-transfers-tool, show-transfer-tool, cancel-transfer-tool |
| Roles | list-permissions-tool, create-permission-tool, update-permission-tool, delete-permission-tool, list-roles-tool, show-role-tool, create-role-tool, update-role-tool, delete-role-tool, list-role-assignments-tool, assign-role-tool, revoke-role-tool, list-user-permissions-tool |
The default API and MCP middleware include throttle:roster: 120 requests per minute per signed-in user, or per IP for guests. Change it with roster.rate_limit.per_minute (null turns it off). Missing records answer 404 {"message": "Not found."} without naming internal classes.
When refactor-circus/cortex is installed, Roster registers its MCP server and every tool with Cortex. Nothing needs registering in your app. Cortex agents can then manage users, organizations and roles, and you can publish new versions of the server instructions and tool descriptions in Cortex.
- Agents act as the signed-in user, so Roster's permission checks apply. A run with no signed-in user is refused.
- Limit what agents see with
roster.cortex.tools(a list of tool names), or turn the integration off withroster.cortex.enabled.
Cortex's own screens (an organization's MCP tab, MCP redirect domains) are Cortex's: it adds them to Roster's screens through Atrium's screen extensions. Roster renders nothing of Cortex's.
When refactor-circus/atrium is installed, Roster registers itself with it automatically. It adds:
- a Users section: list, filter, create, edit account and profile, suspend/deactivate/reactivate, delete, memberships and context switching
- an Organizations section: members, ownership, teams, invitations, settings (domains, auto-join) and external records (link, unlink; filter the list by source, external id or account number)
- Roles and Permissions sections, a Roles card on each user, and a Roles tab on each organization
- Impersonations (active and history, end any) and an Impersonate card on each user
- Imports & exports: upload a CSV, review the preview, confirm or cancel, follow progress, and download exports, also reached from each organization and from Users
- "Users by status" and "Organizations" widgets
- navigation, widgets and search hidden from users without the matching permission
- on every page, only the controls the viewer may use: each form, button and organization tab asks the same permission, in the same organization or team, as the action behind it (Impersonate needs
roster.users.impersonate, the Roles cardroster.roles.view, assigningroster.roles.assign, each import or export type its own permission, and so on). Opening a tab you may not see is refused. Published views can do the same with@rosterCan('roster.users.update', $organization, $self) ... @endrosterCan - search over users and organizations, matching from the start of a name, email or slug (the Users and Organizations screens' filters match anywhere)
Access follows Atrium's viewAtrium gate. To hide it, add 'roster' to atrium.disabled. Roster can also be switched by feature flag. roster.atrium.features lists the features that must all be on: while any is off, Roster's navigation, widgets and search disappear and its pages answer 404. Atrium asks its feature resolver, so Pennant (through refactor-circus/pennantplus) or any other flag system decides.
By default it lists RefactorCircus\Roster\Atrium\Features\RosterSupportFeature, a PennantPlus feature that is on until its global value is set. Its SupportFeature suffix matches PennantPlus's gate.global_only pattern, so only the global value counts and who sees which page stays with Roster's permissions. Turn Roster off for everyone with Feature::for(null)->deactivate(RosterSupportFeature::class) or from the Feature flags page. Without refactor-circus/pennantplus the class is skipped and nothing is checked.
To change the default, point the config at a subclass:
use RefactorCircus\Roster\Atrium\Features\RosterSupportFeature;
class RosterFeature extends RosterSupportFeature
{
protected function default(): bool
{
return false; // off until switched on
}
}
// config/roster.php
'atrium' => ['features' => [App\Features\RosterFeature::class]],A class name that no longer ends in SupportFeature also follows per-user values.
Every Roster dashboard screen declares itself to Atrium's screen extensions registry, so your app and other packages can add tabs and sections to it (an organization's orders, a user's devices) without publishing Roster's views. Roster renders no other package's UI: Keen's history and Cortex's MCP screens arrive the same way. Registering, visibility, closures, ?tab= and duplicate keys follow Atrium's rules, described in Atrium's README; this section covers what Roster declares.
Register from a service provider's boot(), never per request. Atrium is optional, so check that it is installed:
use Illuminate\Database\Eloquent\Model;
use Illuminate\Http\Request;
use RefactorCircus\Atrium\Domains\Screens\Data\Screen;
use RefactorCircus\Atrium\Domains\Screens\Data\SectionDefinition;
use RefactorCircus\Atrium\Domains\Screens\Data\TabDefinition;
use RefactorCircus\Atrium\Facades\Atrium;
public function boot(): void
{
if (! class_exists(Atrium::class)) {
return;
}
Atrium::screens()
// A tab on each organization, opened with ?tab=acme.orders.
->tab('roster.organization', TabDefinition::make('acme.orders')
->label('Orders')
->icon('shopping-cart')
->view('acme::roster.orders')
->permission('orders.view')
->resolve(fn (?Model $organization, Screen $screen): array => [
'orders' => Order::where('organization_id', $organization?->getKey())->latest()->limit(50)->get(),
]))
// A section beside each user's page.
->section('roster.user', 'aside', SectionDefinition::make('acme.devices')
->component('acme::user-devices')
->authorize(fn (Request $request, ?Model $user, Screen $screen): bool => $request->user()?->is($user) === true)
->resolve(fn (?Model $user, Screen $screen): array => ['devices' => $user?->devices ?? []]))
// A control in each row of the Users list, for those who may update that user.
->section('roster.users', 'row.actions', SectionDefinition::make('acme.reset-devices')
->view('acme::roster.reset-devices')
->permission('roster.users.update'));
}Screens. Each screen builds Screen::standard() with its key and kind, so it has exactly the standard slots: header.actions, before and after on every screen, plus aside on a detail screen or the row slot row.actions (rendered once per row, with the row as $record) on a list screen.
| Key | Page | Kind | Record | Slots |
|---|---|---|---|---|
roster.users |
Users list | list | none; each row is a user | header.actions, before, after, row.actions |
roster.user-create |
New user | detail | none | header.actions, before, after, aside |
roster.user |
A user | detail | the user | header.actions, before, after, aside |
roster.organizations |
Organizations list | list | none; each row is an organization | header.actions, before, after, row.actions |
roster.organization-create |
New organization | detail | none | header.actions, before, after, aside |
roster.organization |
An organization | detail | the organization | header.actions, before, after, aside |
roster.team |
A team | detail | the team | header.actions, before, after, aside |
roster.roles |
Roles list | list | none; each row is a role | header.actions, before, after, row.actions |
roster.role |
A role | detail | the role | header.actions, before, after, aside |
roster.permissions |
Permissions list | list | none; each row is a permission | header.actions, before, after, row.actions |
roster.impersonations |
Impersonations list | list | none; each row is an impersonation | header.actions, before, after, row.actions |
roster.transfers |
Imports & exports list | list | none; each row is a transfer | header.actions, before, after, row.actions |
roster.transfer |
An import or export | detail | the transfer | header.actions, before, after, aside |
roster.invitation |
The invitation page (/roster/invitation/{token}) |
detail | the invitation | header.actions, before, after, aside |
Deleted users and organizations show their deleted page, which is not a screen: registered tabs and sections never show there, and their closures never run. The CSV template download is not a screen either.
Built-in tabs. Every screen but roster.organization has one built-in tab, overview, holding the page; the tab bar appears only once a registered tab is visible to the viewer. The organization screen's built-in tabs are members, teams, invitations, roles and settings, in that order, each shown only to viewers holding its permission in the organization; the first one shown is the default. All five keys are reserved for every viewer, including the tabs a viewer may not open: a registered tab named like one is skipped and reported, and shows to no one. ?tab= naming a built-in tab the viewer may not open answers 403, and an unknown key (?tab=activity, ?tab=mcp, ?tab=sso and ?tab=scim included, which were Roster's tabs before) opens the default tab. New built-in keys may arrive in minor releases, so prefix yours with your vendor, as vendor.key (acme.orders).
Access. A permission() tab or section asks the screen's access closure, which is ScreenAccess::allowsOn($permission, $record): the same check, in the same scope, as Roster's own controls and @rosterCan. In a row slot, $record is the row.
$record |
Asked as |
|---|---|
OrganizationModel or TeamModel |
ScreenAccess::allows($permission, $record): in that organization or team |
an instance of the configured roster.users.model |
ScreenAccess::allows($permission, null, $record): about that user |
RoleModel |
ScreenAccess::allows($permission, $record->organization): in its organization, or globally for a shared role |
ImpersonationModel |
ScreenAccess::allows($permission, $record->organization): in its organization, or globally without one |
TransferModel |
ScreenAccess::allows($permission, $record->organization, $record->requester): in its organization, about its requester when it has one |
InvitationModel |
ScreenAccess::allows($permission, $record->organization): in its organization |
| none (list and create screens) | ScreenAccess::allows($permission) |
| any other model | refused |
Roster checks the viewer may open the screen first, so your authorize closures and resolvers never run for a viewer refused it. With an authorize() closure and a permission(), both must pass; public() shows an extension to anyone who may open the screen, so prefer a permission or a closure when your data is more sensitive than the screen.
Rendering. While a registered tab is open its panel replaces the page, with only header.actions around it, and the organization and user screens load none of their own data. On the organization screen only the open built-in tab's data is loaded. A tab or section view receives your resolver's data with Atrium's screen, record and tab over it; a component receives the resolver's data as one data prop.
Testing. Registrations otherwise outlive a test: use Atrium's RefactorCircus\Atrium\Testing\ResetsScreenExtensions on your test case.
If you published Roster's views (roster-views), re-publish them (php artisan vendor:publish --tag="roster-views" --force): older copies render no screen tabs or sections.
Other packages, and your app, add authorization resources, permissions, membership sources, sign-in requirements and audit context to Roster through registration points, without Roster naming them; refactor-circus/guardian, for one, adds single sign-on and provisioning this way. Register from a service provider's boot(), never per request. Each registry is a singleton holding code-defined state for the life of the process (Octane, queue workers), and registering the same thing twice throws.
roster.* is Roster's. Resource prefixes and permission names under roster.* are reserved for Roster's own domains: resource() and permission() throw an InvalidArgumentException naming the value for any of them. Register under your package's own prefix, such as acme.widgets.
A resource lets your model's Gate policy answer the permissions named after it in every one of Roster's checks: API and MCP requests, ScreenAccess, @rosterCan and Authorizer::check(). Register a prefix with its model, and permission {prefix}.{verb} asks that model's policy by the camel-cased verb, exactly as roster.users.manage-status asks UserPolicy::manageStatus():
use Acme\Widgets\Models\WidgetModel;
use Acme\Widgets\Policies\WidgetPolicy;
use Illuminate\Support\Facades\Gate;
use RefactorCircus\Roster\Domains\Permission\Services\Resources;
public function boot(): void
{
app(Resources::class)->resource('acme.widgets', WidgetModel::class);
Gate::policy(WidgetModel::class, WidgetPolicy::class);
}use Illuminate\Database\Eloquent\Model;
use RefactorCircus\Roster\Support\Policies\Policy;
final class WidgetPolicy extends Policy
{
// `acme.widgets.approve`, checked in the widget's organization or team.
public function approve(?Model $user, ?Model $subject = null, ?Model $self = null): bool
{
return $this->permits($user, 'acme.widgets.approve', $subject, $self);
}
}- A prefix is two lower-case segments of letters, digits and dashes (
acme.widgets). An invalid prefix, aroster.*one, or one already registered throws anInvalidArgumentExceptionnaming it. - A permission's prefix is everything before its last dot, so
acme.widgets.approve.alllooks upacme.widgets.approve. A permission whose prefix nothing registers asks no policy and is refused. - Register the model's policy too. A registered model without one makes the check throw an
InvalidArgumentExceptionnaming the resource, the first time a permission resolves to it. A missing policy never counts as an allow. - Asked with a record,
permits()finds its organization or team through itsorganization_id/team_idattribute or itsorganization()/team()relation, whichever it has, as for Roster's own models. - A resource registered after checks have run still counts:
Resourceskeeps its owngeneration(), and the answers remembered for the request start over when it changes.
Add your permissions to Roster's catalogue so they are created as system permissions, and say which built-in roles (admin, member, lead) they go to:
use RefactorCircus\Roster\Domains\Permission\Services\PermissionCatalogue;
public function boot(): void
{
app(PermissionCatalogue::class)
->permission('acme.widgets.view', 'See widgets.', ['admin', 'member'])
->permission('acme.widgets.approve', 'Approve widgets.', ['admin']);
}- The role-tables migration,
BuiltInRoles::sync()andphp artisan roster:sync-permissionscreate them. A package registered after that migration ran (installed later, or upgraded with new permissions) needsphp artisan roster:sync-permissionsto create its permissions. - Existing built-in roles never gain a newly registered permission automatically: the grants apply only to the built-in roles the sync creates, so grant the permission to existing roles by hand, in Atrium or through the role API. Grants an app has changed are never altered.
- A name registered twice, a
roster.*name, or a role that is not built in throws anInvalidArgumentExceptionnaming it.roster:sync-permissionswarns about system permissions in the database that nothing registers any more, and leaves them in place. - The impersonation-blocked list stays core-only: registered permissions are never added to
roster.impersonation.blocked. If yours must not run while someone is impersonating, add its pattern there yourself ('acme.widgets.*').
A membership records how the user joined. Register your package's way in, with the label members show for it:
use RefactorCircus\Roster\Domains\Organization\Services\MembershipSources;
public function boot(): void
{
app(MembershipSources::class)->register('hris', 'HR system');
}$membership->sourceis the stored string. Roster's built-in sources are theMembershipSourcecases (direct,invitation,domain,personal,import), and$membership->sourceEnum()answers the case, or null for a registered source such ashris.- The API and MCP member data show the registered label (
HR system). A stored source that nothing registers, from a package you removed for example, shows its stored value and never errors. - Code that joins users through Roster's
ManagesMemberships::join()passes a registered source as a string. An unregistered one throws anInvalidArgumentException, as does registering a built-in value or the same source twice.
A sign-in requirement says that an email must sign in somewhere else, such as an identity provider, instead of with a password. Guardian's single sign-on enforcement is one. Roster has no password login of its own; add the NoExternalSignIn rule to yours, and it fails for any email a registered sign-in requirement claims, with a link to where that sign-in starts:
use RefactorCircus\Roster\Support\Rules\NoExternalSignIn;
$request->validate(['email' => ['required', 'email', new NoExternalSignIn]]);Register your own requirement the same way Guardian does:
use RefactorCircus\Roster\Contracts\SignInRequirement;
use RefactorCircus\Roster\Data\ExternalSignIn;
final class PartnerSignIn implements SignInRequirement
{
public function for(string $email): ?ExternalSignIn
{
if (! str_ends_with(strtolower($email), '@partner.example')) {
return null;
}
return new ExternalSignIn(key: 'partner', label: 'Partner Inc.', url: route('partner.sign-in'));
}
}use RefactorCircus\Roster\Facades\Roster;
public function boot(): void
{
Roster::requireSignIn(PartnerSignIn::class);
}
Roster::externalSignInFor('ada@partner.example')?->url; // where her sign-in startsexternalSignInFor()asks the requirements in registration order and returns the first answer that isn't null. Requirements must not overlap: make sure no two claim the same emails. A class-string is resolved from the container once, on first use, and registering the same class or instance again is ignored.- Super-admins get
nullbefore any requirement is asked, so a broken requirement can't lock them out. - It fails closed. A requirement that throws is not caught: the login or registration asking (through
NoExternalSignIn) fails, Laravel's handler reports the exception, and the user sees a generic error, never its message. This is deliberate for a security control, so keep requirements simple. - The
NoExternalSignInrule fails with the translatedroster::roster.external_sign_in_requiredmessage, its:organizationfrom the answer'slabeland:urlfrom itsurl.ExternalSignIn::$recordholds whatever record a registered sign-in requirement keeps behind its answer, if any. - With no requirement registered (no Guardian, say), every email passes the rule, so organizations that enforced single sign-on accept password sign-in.
Roster::provisionedStatus() is the provisioning API. Accounts your package creates for an organization from outside (externally provisioned accounts, such as Guardian's) start with the status it returns:
use RefactorCircus\Roster\Facades\Roster;
$status = Roster::provisionedStatus($organization); // an AccountStatus, such as UserStatus::PendingIt is the organization's provisioned_status, resolved through the user statuses in roster.statuses.users. An organization with none starts its accounts as active(). A stored value the status enum doesn't know falls back to active() and is reported, so provisioning never fails and a bad value is never silent.
Roster has no audit API. To add context to the audit entries of Roster's changes, register a closure on refactor-circus/keystone's AuditHooks. AuditHooks runs every context closure for every package's events and catches nothing, so the closure keeps to Roster's entries itself and never lets an exception out:
use RefactorCircus\Keystone\Audit\AuditHooks;
use RefactorCircus\Keystone\Packages\PackageRegistry;
use RefactorCircus\Roster\Facades\Roster;
public function boot(): void
{
// Once every provider has booted, when Roster registers its own hooks.
$this->app->booted(function (): void {
if (! Roster::auditing()) {
return;
}
app(AuditHooks::class)->context(function (object $event): array {
try {
if (app(PackageRegistry::class)->for($event)?->key !== 'roster') {
return [];
}
$device = app(DeviceContext::class)->current();
return $device === null ? [] : ['acme_device' => ['id' => $device->id, 'name' => $device->name]];
} catch (Throwable $e) {
report($e);
return [];
}
});
});
}- Return
[]when you have nothing to add, nevernull:AuditHooksspreads every closure's result into the entry. - On a failure the closure reports the exception and the entry is still written, without your key.
The workbench is a demo app with Atrium and seeded data:
composer serveIt signs you in as the super-admin admin@example.com (password password) and opens /atrium. You'll find organizations Acme and Globex with teams, members and a pending invitation, plus a custom invoices.edit permission and a Billing role. The JSON API is mounted at /roster. To run the MCP server over stdio:
php vendor/bin/testbench mcp:start rostercomposer test # static analysis, formatting, type coverage, Pest
composer test:browser # Atrium in a real browser (run `npm install` first for Playwright)composer test includes tests/Modes/AtriumUnavailable, which boots Roster without registering its Atrium wiring. Atrium is still installed there as a dev dependency, so CI also runs that mode with Atrium (and Cortex and Impex, which require it) uninstalled. To reproduce that lane, work in a scratch worktree so your own vendor stays as it is:
git worktree add ../roster-without-atrium HEAD
cd ../roster-without-atrium
composer remove --dev --no-update refactor-circus/atrium refactor-circus/cortex refactor-circus/impex
composer update --no-interaction --no-scripts
php -r "require 'vendor/autoload.php'; exit(class_exists('RefactorCircus\\Atrium\\Atrium') ? 1 : 0);"
vendor/bin/pest tests/Modes/AtriumUnavailableRemove it afterwards with git worktree remove --force ../roster-without-atrium.
Please see CHANGELOG for more information on what has changed recently.
Thank you for considering contributing to Roster! Please review our contributing guide to get started.
Please review our security policy on how to report security vulnerabilities.
Roster is open-sourced software licensed under the MIT license.