Invitations

Let a privileged operator invite a new user by email — issue a single-use link, the invitee sets a password and lands in the app — instead of leaving self-service registration open to the world.

Why this exists

Invitations let a privileged operator bring users into an app that has no open /register page. The module is a package-owned InvitationManager plus a public accept screen, wired through the same RegistersUsers pipeline the rest of authentication uses.

Invite-only onboarding (agencies, internal tools, B2B admin panels, anything with a closed user base) is a different shape: a privileged operator decides who gets in, the invitee never chooses their own email, and the whole thing has to be safe against token-guessing and link-sharing.

Two-layer guard

Invitations are opt-in. Two independent controls decide whether the feature does anything:

1. Master switch — martis.invitations.enabled (default false). Set MARTIS_INVITATIONS_ENABLED=true in the env to turn it on. While off, the accept routes always 503 and the resource scaffolded by the generator (see below) hides itself from navigation and routing.
2. Authorisation gate — martis-invite. The package registers a deny-by-default definition (Gate::define('martis-invite', fn () => false)) so an unconfigured install cannot issue invitations by accident. Define your own in App\Providers\AuthServiceProvider::boot() to decide who may invite:

use Illuminate\Support\Facades\Gate;
 
Gate::define('martis-invite', function ($user) {
    return $user?->hasRole('admin');
    // Or: $user?->is_admin;
    // Or: $user?->email && str_ends_with($user->email, '@yourcompany.com');
});

The gate only guards the privileged issue action (wherever you call InvitationManager::invite() from — typically the InviteUser action the generator scaffolds). Accepting an invitation is token-authorized, not gate-authorized: the invitee has no account yet, so neither martis.auth nor martis-invite apply to the public accept endpoints.

Configuration

// config/martis.php
'invitations' => [
    'enabled' => env('MARTIS_INVITATIONS_ENABLED', false),
    'expires_after_hours' => (int) env('MARTIS_INVITATIONS_TTL_HOURS', 72),
    'single_use' => true,
    'resend_throttle_seconds' => (int) env('MARTIS_INVITATIONS_RESEND_THROTTLE', 60),
    'login_after_accept' => env('MARTIS_INVITATIONS_LOGIN_AFTER_ACCEPT', true),
    'redirect_after_accept' => env('MARTIS_INVITATIONS_REDIRECT', null),
    'signup_fields' => ['name', 'password'],
    'mark_email_verified_on_accept' => true,
],
 
'audit' => [
    // ... other audit toggles
    'invitations' => env('MARTIS_AUDIT_INVITATIONS', true),
],

Upgrading from before this key shipped? The base config stub carries audit.invitations, so a fresh vendor:publish --tag=martis-config is covered. If your config/martis.php was published earlier and you run config:cache (the common production and Docker path), the cached snapshot is built from your published file and Laravel's package-config merge is skipped, so a missing audit.invitations leaves MARTIS_AUDIT_INVITATIONS inert. Running php artisan martis:invitations backfills the key into your existing audit array (idempotent — a second run is a no-op); or add 'invitations' => env('MARTIS_AUDIT_INVITATIONS', true), to the array by hand.

Lifecycle

An invitation moves through a small state machine: pending → accepted or revoked. There is no manual expired transition — expiry is evaluated at read time (isExpired()) and enforced at claim time in accept().

Issue

use Martis\Invitations\InvitationManager;
 
$invitation = app(InvitationManager::class)->invite(
    email: 'new.hire@example.com',
    role: 'editor',       // optional; assigned to the user on accept if the model supports assignRole()
    metadata: [],          // optional opaque bag — see below
);
 
// $invitation->rawToken holds the plain-text token, in memory only,
// for exactly this request — build the accept URL and send it now.

invite() generates a CSPRNG token, persists only its hash, sets expires_at from expires_after_hours, records invited_by from the currently authenticated guard user, and fires InvitationCreated.

Accept

$user = app(InvitationManager::class)->accept($rawToken, [
    'name' => 'Jane Doe',
    'password' => '...',
    'password_confirmation' => '...',
]);

accept() runs inside a single DB transaction:

1. Atomically claims the invitation (pending → accepted, compare-and-set UPDATE). If nothing was claimed — unknown token, already accepted, revoked, or expired — it throws InvalidInvitationException and the transaction rolls back.
2. Rejects if the invitation's email already belongs to a registered user (anti-takeover).
3. Filters the incoming signup payload down to signup_fields and calls the createUser() override seam.
4. Assigns the invitation's role, if any, via assignRole() when the resulting user model supports it (Spatie soft-dependency).
5. Optionally stamps email_verified_at.
6. Fires InvitationAccepted only after the transaction actually commits (DB::afterCommit), so a rolled-back claim never emits the event.

A validation failure inside createUser() (short password, mismatched confirmation, …) propagates out of accept() unchanged as a ValidationException — the transaction rolls back and the invitation returns to pending, so the invitee can simply retry with a fixed payload.

Resend

app(InvitationManager::class)->resend($invitation);
// $invitation->rawToken now holds a fresh plain-text token; the old one stops working.

Only works on a still-pending invitation, and is throttled by resend_throttle_seconds against the row's updated_at. Both failure modes throw InvalidInvitationException.

Revoke

app(InvitationManager::class)->revoke($invitation);

Flips a still-pending invitation to revoked, permanently blocking its accept link, and fires InvitationRevoked. Revoking a non-pending invitation throws InvalidInvitationException.

Security posture

• Hashed at rest. The plain-text token is a 32-byte CSPRNG value (random_bytes(32), base64url-encoded); only its SHA-256 hash is ever written to the token column. The plain value lives on $invitation->rawToken — an in-memory-only property, never fillable, never cast — for exactly the request that minted or resent it.
• Atomic single-use. The pending→accepted transition is a single compare-and-set UPDATE …WHERE status = 'pending', not a read-then-write. The row lock it takes serializes concurrent accept attempts on the same token, so a token cannot be claimed twice even under a race.
• Out of the request line. The emailed link is /invitations/accept#token=… (v2.6.0): the token is in the URL fragment, which the browser never sends, so proxy and web-server access logs never record it. A link mailed before v2.6.0 (/invitations/accept/{token}) is redirected to that form. See authentication.md § One-time links keep the token out of the request line.
• Enumeration-neutral. GET /invitations/accept never sees the token and always returns the same 200 + SPA shell, and the legacy GET /invitations/accept/{token} answers the same redirect whether the token is valid, unknown, expired, revoked, or already used — the server never signals validity from the page load. The POST accept endpoint collapses every unacceptable state (unknown, expired, revoked, used, email-already-registered) into the same generic InvalidInvitationException message, so probing the endpoint cannot distinguish "no such token" from "already claimed".
• Signup whitelist. accept() only reads keys listed in signup_fields (plus password_confirmation) from the client payload. email is never client-controlled — it always comes from the invitation row.
• Existing-email guard. An invitation whose email already belongs to a registered user is rejected (and the claim rolled back) rather than silently overwriting or duplicating an account.
• The role is checked where the invitation is issued. The scaffolded InviteUser validates the role on the server against the list the picker shows (no SSO-managed role, and a delegate only the roles they hold), so a forged fields.role cannot mint an invitation for a role the inviter may not grant. See The invite role picker. invite() itself stores the role it is given: if you call it from your own code, check the role there.

The InvitationManager API

The override seam: createUser()

InvitationManager::createUser() is the only method meant to be overridden. Its default implementation builds an in-memory Request (name/password from the whitelisted signup payload, email authoritative from the invitation) and delegates to the same Martis\Contracts\RegistersUsers binding self-service registration uses — one registration pipeline, one place to change validation, hashing, and default-role assignment app-wide.

Subclass the manager when an invitation needs to shape the user differently from a self-registered one — for example, carrying arbitrary data through metadata and writing it onto the new user:

namespace App\Invitations;
 
use Illuminate\Contracts\Auth\Authenticatable;
use Martis\Invitations\Invitation;
use Martis\Invitations\InvitationManager;
 
class AppInvitationManager extends InvitationManager
{
    protected function createUser(Invitation $invitation, array $signup): Authenticatable
    {
        $user = parent::createUser($invitation, $signup);
 
        // $invitation->metadata is whatever opaque bag invite() was called with.
        if ($departmentId = $invitation->metadata['department_id'] ?? null) {
            $user->forceFill(['department_id' => $departmentId])->save();
        }
 
        return $user;
    }
}

Rebind it in your service provider so the package resolves your subclass everywhere:

$this->app->bind(InvitationManager::class, AppInvitationManager::class);

Do not reach for this seam for app-wide registration changes — rebind RegistersUsers instead (see authentication.md). Override createUser() only for behaviour specific to the invitation flow (reading metadata, skipping a step self-registration always does, etc).

Events + audit

Three events, one per lifecycle transition, all carrying the Invitation:

The package's own Martis\Invitations\Listeners\RecordInvitation subscribes to all three and writes a martis_action_events row per transition (invitation.created / invitation.accepted / invitation.revoked), skipping silently when the audit table is missing. Toggle the row write off per-environment with MARTIS_AUDIT_INVITATIONS=false — the events still fire, so any listener you attach keeps firing; only the built-in audit row is suppressed.

Attach your own listeners the same way you would for any Laravel event:

use Illuminate\Support\Facades\Event;
use Martis\Invitations\Events\InvitationAccepted;
 
Event::listen(InvitationAccepted::class, function (InvitationAccepted $e) {
    \App\Notifications\SecurityWebhook::send([
        'invited_email' => $e->invitation->email,
        'user_id' => $e->user->getAuthIdentifier(),
    ]);
});

The accept-URL seam (InvitationUrl)

The URL an invite notification points at is built through a static, overridable seam, mirroring Laravel's own Illuminate\Auth\Notifications\ResetPassword::createUrlUsing():

use Martis\Invitations\Invitation;
use Martis\Invitations\InvitationUrl;
 
InvitationUrl::createUrlUsing(function (Invitation $invitation, string $rawToken): string {
    return 'https://accounts.example.com/invite#token='.rawurlencode($rawToken);
});

MartisServiceProvider::boot() seeds the package default (TokenLink::url('martis.invitations.accept', ['token' => $rawToken]): /{martis-path}/invitations/accept#token=… on APP_URL) automatically, but only when martis.invitations.enabled is true and no callback is already registered — so a consumer's own registration (in AppServiceProvider::boot(), run before the package's) always wins. Reach for this when the accept link needs to point somewhere other than the bundled SPA route: an off-platform signup page, a deep link into a mobile app, or a URL that needs extra query parameters. Keep the token itself in the fragment (or the body of a POST), never in the path or the query string, so access logs never record it.

Pass null to reset to the package default.

Public accept surface

Two routes, always registered regardless of the master switch (so the route table stays predictable across environments) — both 503 while martis.invitations.enabled is false:

token, plus each configured signup_fields entry, plus password (always confirmed, and your password rules: Password::defaults(), else Password::min(8)) are the only fields the POST endpoint validates. The password rules are checked once: by the default RegistersUsers the accept hands the signup to, or by the endpoint itself when you bind a registrar of your own, which may not check them (so uncompromised() asks Have I Been Pwned once per accept). An InvalidInvitationException from the manager becomes a neutral 422 { message, errors: { token: [message] } } (JSON) or a redirect back to /login with a flashed error (non-JSON) — the same shape regardless of which invalid state it was.

React accept screen

The package ships a working accept screen — resources/js/pages/InvitationAccept.tsx — mounted at /invitations/accept. It reads the token from the URL fragment (useAuthLinkParams()), drops it from the address bar, and renders the set-password form optimistically (the GET never reveals whether the token is valid) and only learns the token was bad from the POST response's errors.token key, at which point it swaps to a neutral "invitation link invalid" state. Every other 422 field error stays inline so the invitee can fix and retry. On success it follows the JSON envelope's redirect with a full page navigation (the accept call just changed session state, so a hard navigation is what picks up the new auth state).

Only the default signup_fields (name, password) render — matching the controller's default validation. Ships translated in en, pt_PT, and pt_BR.

Overriding the screen

Register a replacement under the auth:invitation-accept key from your consumer extension bundle:

import { componentRegistry } from '@martis/runtime'
import { MyInvitationAccept } from './components/MyInvitationAccept'
 
componentRegistry.register('auth:invitation-accept', MyInvitationAccept)

The replacement reads the token with useAuthLinkParams() from @martis/runtime (since v2.6.0 it is in the URL fragment, not a route parameter) and posts it to /api/invitations/accept:

import { useAuthLinkParams } from '@martis/runtime'
 
export function MyInvitationAccept() {
  const { token } = useAuthLinkParams()
  // ... POST { token, name, password, password_confirmation }
}

The router resolves this key the same way it resolves auth:login, auth:register, and the other auth-page slots — a missing registration falls back to the bundled default. There is no dedicated martis:component --type= scaffold for this slot yet; the registry key works for any string, scaffolded or not, so registering it directly (as above) is the supported path.

Copy overrides

Two of the same two paths every other auth screen supports (see authentication.md § Customising the auth copy):

• Path 1 (lang files) — invitation_accept_title / invitation_accept_sub keys in the published auth.php lang file.
• Path 2 (config) — config('martis.auth.copy.invitation_accept.title') / .subtitle, string or array<locale, string>.

The martis:invitations generator

php artisan martis:invitations

Everything above ships inside the package. What cannot live there — because it belongs in your application's own namespace and is meant to be edited — is scaffolded by this one-shot generator:

It also publishes the create_invitations_table migration (a portable, key-type-aware stub: invited_by and accepted_user_id reference the table of the Martis guard's users, users on a default install, and match its primary-key shape), runs it, and, if you published config/martis.php before the invitations block existed, inserts the block for you. Every step is idempotent; re-running the command is a no-op once the app is set up, and nothing is overwritten without --force. The migration is dated after the newest migration already in database/migrations.

Options:

After the command finishes: set MARTIS_INVITATIONS_ENABLED=true, define the martis-invite gate, and visit the System sidebar group.

The invite role picker

Accepting an invitation assigns the invitation's role (assignRole()), so the role is the sensitive input of the InviteUser action. InvitationManager::invite() stores whatever role it is given, as a primitive should: deciding who may hand out which role is the caller's job, and the scaffolded action does it on the server (v2.4.0+), not only in the picker. A fields.role the picker never offered answers 422 on the field, mints no invitation and sends no mail.

One private method of the generated action, assignableRoles(), holds the list, and the picker, the Select's validateAgainstOptions() rule and a second check in handle() all read it:

• SSO-managed roles (a non-null provider_group_name) are never offered or accepted: group sync owns them and would overwrite them at the next sign-in.
• Who may invite into which role. An admin (the hasRole('admin') check InvitationPolicy makes) or anyone who passes the martis-invite-any-role ability may invite into every remaining role. Anyone else is a delegate and may only hand out the roles they hold themselves. So when you delegate martis-invite to a non-admin role, that role cannot be used to mint an invitation for a role above its own, which would let the delegate invite a second address as an admin and accept it.
• Granting a wider list on purpose is one Gate definition, next to martis-invite (below).
• No roles package, or no role chosen. Without spatie/laravel-permission the list is empty and an invitation carries no role; leaving the picker empty always works.

// App\Providers\AuthServiceProvider::boot()
Gate::define('martis-invite', fn ($user) => $user->hasRole('hr-manager'));
Gate::define('martis-invite-any-role', fn ($user) => $user->hasRole('hr-manager'));

Without the second line an hr-manager can invite into hr-manager only. Edit mayInviteIntoAnyRole() in the action if your app delegates in another way (a permission, a per-role ability).

An InviteUser generated before v2.4.0 keeps the old behaviour (any role name was accepted). Regenerate it with php artisan martis:invitations --force after merging your edits, or take the three changes by hand: build the list once in assignableRoles(), add ->validateAgainstOptions() to the Select, and refuse a role outside the list in handle().

Recipes

Consumer-land recipe (not shipped in the package)

Multi-tenant SaaS admin: every invitation belongs to a tenant, the invited user must land inside that tenant, and only tenant admins may invite within their own tenant. None of this is package behaviour — it's composed entirely from the seams above.

1. Carry the tenant on the invitation and read it back in createUser():

namespace App\Invitations;
 
use Illuminate\Contracts\Auth\Authenticatable;
use Martis\Invitations\Invitation;
use Martis\Invitations\InvitationManager;
 
class TenantInvitationManager extends InvitationManager
{
    protected function createUser(Invitation $invitation, array $signup): Authenticatable
    {
        $user = parent::createUser($invitation, $signup);
 
        $user->forceFill([
            'tenant_id' => $invitation->metadata['tenant_id'] ?? null,
        ])->save();
 
        return $user;
    }
}

// App\Providers\AppServiceProvider::register()
$this->app->bind(
    \Martis\Invitations\InvitationManager::class,
    \App\Invitations\TenantInvitationManager::class,
);

Issue an invitation carrying the current operator's tenant:

app(InvitationManager::class)->invite(
    email: $email,
    role: $role,
    metadata: ['tenant_id' => auth()->user()->tenant_id],
);

2. Scope who may invite to their own tenant:

// App\Providers\AuthServiceProvider::boot()
Gate::define('martis-invite', fn ($user) => $user?->tenant_id !== null && $user->hasRole('admin'));

3. Scope the generated resource to the current tenant (edit the generated InvitationResource):

public static function indexQuery(Request $request, Builder $query): Builder
{
    return $query->where(
        'metadata->tenant_id',
        $request->user()->tenant_id,
    );
}

4. Restrict the roles to the ones the current tenant actually uses (edit assignableRoles() in the generated InviteUser action). The picker, the Select's validation and the check in handle() all read that method, so one clause restricts all three:

$query = \Spatie\Permission\Models\Role::query()
    ->where('tenant_id', $inviter?->tenant_id);

Nothing here required forking the package: one manager subclass, one gate definition, one indexQuery() override, and one query clause.

Tests

Behaviour-level coverage lives across tests/Feature/Invitation*Test.php: InvitationModelTest, InvitationConfigTest, InvitationManagerTest, InvitationControllerTest, InvitationAuditTest, InvitationsMigrationTest, InvitationsScaffoldCommandTest — the full state-machine, security-invariant, and generator-idempotency matrix. The React accept screen has its own coverage in resources/js/pages/InvitationAccept.test.tsx.