Quickstart

This is the 60‑second tour. For a deep treatment of why redemption is correct under load, read
Atomic idempotent redemption.

1. Install

composer require padosoft/laravel-invitations
php artisan migrate

Make your user model invitation‑aware:

use Illuminate\Foundation\Auth\User as Authenticatable;
use Padosoft\Invitations\Concerns\InteractsWithInvitations;
use Padosoft\Invitations\Contracts\InvitedAccount;

class User extends Authenticatable implements InvitedAccount
{
    use InteractsWithInvitations; // reads `email` + auth guard for the engine
}

Full details (publishing config / routes / migrations) are in Installation.

2. Generate codes (PHP)

use Padosoft\Invitations\Services\CodeGenerator;

$code  = app(CodeGenerator::class)->generateRandom(['max_uses' => 100]);
$batch = app(CodeGenerator::class)->generateBatch(500); // 500 distinct codes

Codes are CSPRNG‑drawn Crockford Base32 (no confusable I L O U), normalized to a canonical form so
the generator and the redeemer agree on identity. See Invite codes.

3. Redeem a code — atomic, idempotent, fraud‑gated

use Padosoft\Invitations\Services\RedemptionService;

$result = app(RedemptionService::class)->redeem($rawCode, $user, [
    'ip'          => $request->ip(),
    'fingerprint' => $request->header('X-Device'),
]);

if ($result->ok) {
    // $result->already === true on an idempotent replay (no second grant)
    // $result->redemption, $result->referral
} else {
    // $result->error: invalid | expired | exhausted | revoked | ineligible | rate_limited
}

4. Over the REST API

Routes auto‑register; attach your own auth / RBAC via config (see
Configuration reference).

POST /api/invitations/redeem       { "code": "Q7K92MNP" }
POST /api/invitations/validate     { "code": "Q7K92MNP" }   # advisory, writes nothing
GET  /api/admin/invitations/metrics
POST /api/admin/invitations/codes  { "count": 50, "max_uses": 1 }

The complete endpoint catalogue is in The HTTP API.

5. Over MCP

Register the bundled tools on your MCP server:

// app/Mcp/Servers/YourServer.php
public array $tools = [
    \Padosoft\Invitations\Mcp\Tools\InviteValidateCodeTool::class,
    \Padosoft\Invitations\Mcp\Tools\InviteGenerateCodesTool::class,
    \Padosoft\Invitations\Mcp\Tools\InviteMetricsTool::class,
];

See The MCP surface and the MCP tools reference.

Where to go next