README

Laravel host-application integration for Sendity.

composer require sendity/laravel-auth

This package is intentionally not the self-hosted Sendity server. It owns the backend Laravel authentication glue and includes an optional Blade component for normal server-rendered Laravel apps:

• resolves the configured Sendity server URL;
• validates RS256 result JWTs issued by the Sendity server;
• exchanges browser authorization tokens into normal Laravel web sessions;
• provisions or reuses Eloquent users through a configurable resolver;
• rejects replayed login tokens;
• exposes a stateless sendity auth guard for advanced Bearer-token requests;
• registers the optional <x-sendity /> Blade wrapper for the Sendity Client.

Configuration

Publish the config:

php artisan vendor:publish --tag=sendity-config

Relevant environment variables:

SENDITY_SERVER_URL=https://sendity.io/api
SENDITY_ISSUER=https://sendity.io
SENDITY_AUDIENCE="${APP_URL}"
SENDITY_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----..."
SENDITY_APP_PUBLIC_KEY=sendity-customer-area
SENDITY_LOGIN_REDIRECT=/dashboard

SENDITY_AUDIENCE should match the public key / app id used when creating auth requests. SENDITY_PUBLIC_KEY accepts either a PEM public key string or a readable file path.

Blade component

For a typical Laravel app, render the hosted widget directly:

<x-sendity>
    <div slot="secondary">Sign in with your passkey</div>
</x-sendity>

The component emits the public Sendity Client contract (public-key plus optional server-url and transport), loads the hosted Sendity Client script once per page by default, forwards Blade slot content into <sendity-auth>, and lets the Client post verified authorizations to the server-owned session_handoff_url returned by the Sendity API. Hosted defaults are used for server-url, server-resolved verification destinations, server-owned session handoff response data and client_script_url when omitted. Publish the bundled client assets only when you intentionally want local pinning or self-hosted assets:

Hosted defaults are intentional: omitting SENDITY_SERVER_URL uses the managed Sendity API at https://sendity.io/api, and omitting verification destinations lets the Sendity Client use the hosted app/channel configuration. Self-hosted applications should set SENDITY_SERVER_URL explicitly and may set SENDITY_CLIENT_SCRIPT_URL=/vendor/sendity/client/sendity-client.js after publishing assets.

php artisan vendor:publish --tag=sendity-assets

Maintainers update the bundled files from the npm package with:

npm ci
npm run sync:sendity-client

Useful config keys:

'ui' => [
    'enabled' => true,
    'component' => 'sendity',
    'public_key' => env('SENDITY_APP_PUBLIC_KEY'),
    'server_url' => env('SENDITY_SERVER_URL', 'https://sendity.io/api'),
    'client_script_url' => 'https://sendity.io/vendor/sendity/client/sendity-client.js',
    'transport' => 'auto',
],

API-only Laravel installations can disable UI registration:

SENDITY_UI_ENABLED=false

Browser session login

By default the package registers:

POST /sendity/session

The Blade component renders <sendity-auth> without a client-side session handoff attribute. After verification, the Sendity Client posts the signed authorization to the same-origin session_handoff_url returned by the Sendity API with Laravel CSRF headers, emits token-free browser events after the handoff succeeds, and follows the JSON redirect response. Configure the app/server response to point at this package route when you want framework-native Laravel session login.

The route validates the authorization field, verifies the JWT, creates or reuses your configured user model, logs the user into Laravel's normal web guard, regenerates the session and returns:

{
  "redirect": "/dashboard"
}

Important config keys:

'login_route' => [
    'enabled' => true,
    'uri' => 'sendity/session',
    'name' => 'sendity.session',
    'middleware' => ['web', 'throttle:10,1'],
],
'login_redirect' => '/dashboard',
'allowed_identifier_types' => ['email'],
'user_model' => App\Models\User::class,
'user_identifier_column' => 'email',
'user_name_column' => 'name',
'user_verified_at_column' => 'email_verified_at',
'create_users' => true,
'mark_verified' => true,

For custom account lookup / provisioning, bind or configure a resolver implementing Sendity\Laravel\SendityUserResolver.

You can also inject Sendity\Laravel\SenditySessionAuthenticator into your own controller when you want full route ownership.

Guard

The sendity guard is for advanced Bearer-token endpoints where the request principal is the Sendity identity itself, not your app's Eloquent user/session.

Register a Laravel guard in your app config:

'guards' => [
    'sendity' => [
        'driver' => 'sendity',
    ],
],

Then protect routes with auth:sendity or resolve the guard manually:

$user = Auth::guard('sendity')->user();

$user->identifier;      // verified email/phone
$user->identifierType;  // email|phone
$user->channel;         // email|whatsapp|...
$user->authRequestId;   // Sendity auth request id

Boundary

Use sendity/laravel-server only for the self-hosted server package. It must stay UI-free. sendity/laravel-auth is the host-app adapter and owns the <x-sendity /> alias.