HTTP API

Balík obsahuje voliteľné JSON endpointy pre každý guard. Zaregistrujete ich cez routes.enabled = true pre guard, alebo explicitne:

// routes/api.php
use RoundlyConsulting\Auth\Facades\Authentication;

Authentication::routes('users');                                      // defaults

Authentication::routes('clients')
    ->prefix('api/clients/auth')
    ->name('clients.auth.')
    ->middleware(['api'])
    ->authenticatedMiddleware(['authentication.active'])
    ->except(['registration', 'invitations.manage']);

RouteRegistrar ponúka prefix(), name(), middleware(), authenticatedMiddleware(), only() a except(); routy zaregistruje pri deštrukcii. Predvolené: prefix {guard}/auth, názvy authentication.{guard}.*, middleware api. Dvojitá registrácia guardu vyhodí výnimku a rovnako aj registrácia guardu na výslednom prefixe či prefixe názvov rout, ktorý už obsadil iný guard (po prefix() / name(), cez routes.enabled aj ručné volanie) — Laravel by ponechal len poslednú routu pre URL; správa uvedie oba guardy. Skupiny pre only() / except(): login, challenge, tokens, registration, invitations, passwords, email, account, sessions, two-factor, passkeys, invitations.manage.

Endpointy

Každá routa má authentication.guard:{guard} a Cache-Control: no-store a existuje len vtedy, ak je jej funkcia pre guard zapnutá (vypnutá funkcia vráti 404). Tokeny vždy putujú v tele požiadavky (JSON). * = vyžaduje prihlásenie (auth:{laravel_guard}); ? = nepovinné.

Každý endpoint, ktorý prihlasuje, prijíma aj device_name? (zobrazí sa v zozname relácií); register a invitations/accept navyše timezone? (uloží sa k novému účtu). Zariadenie sa číta z hlavičky X-Device-Id (activity.new_device.header), jazyk z X-Locale / Accept-Language. credential je JSON objektu PublicKeyCredential z prehliadača s členmi v base64url, doplnený o ceremonyId options, na ktoré odpovedá.

Odpovede

// 200 — authenticated
{ "status": "authenticated", "token_type": "Bearer", "access_token": "eyJ…", "expires_in": 900,
  "expires_at": "2026-09-26T10:15:00Z", "refresh_token": "…", "refresh_expires_at": "2026-10-26T10:00:00Z",
  "session_id": "0199…" }

// 200 — challenge
{ "status": "challenge", "challenge_token": "…", "expires_at": "…", "attempts_left": 5, "method": "password",
  "completed": [], "remaining": [ { "step": "second_factor", "methods": ["totp", "recovery_code", "passkey"] } ] }

// 202 — enumeration-safe acknowledgement (magic link, email code, forgot, resend, email change)
{ "status": "sent" }

// error
{ "message": "…", "code": "invalid_credentials", "errors": { "identifier": ["…"] } }

Odpovede na zmenu prihlasovacích údajov (PUT password, POST two-factor/confirm, DELETE two-factor, POST two-factor/recovery-codes, POST passkeys, DELETE passkeys/{passkey}) obsahujú tokens alebo null. Ak nie je null, klient musí okamžite prejsť na nový pár — jeho predošlý prístupový token so zmenou zanikol.

Chyby

Úprava chybovej odpovede

Každá výnimka balíka sa vykreslí sama — {message, code, errors?, …extra} s Cache-Control: no-store — a globálneho handlera sa nedotkne. Handler Laravelu (rovnaký v Laraveli 12 aj 13) najprv použije mapovače $exceptions->map(), potom nechá odpovedať výnimku s vlastnou metódou render() a až potom spustí callbacky $exceptions->render() / renderable(). Callback render() pre výnimku balíka sa preto nikdy nespustí. Fungujú dva háčiky:

use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Http\Request;
use RoundlyConsulting\Auth\Exceptions\AuthenticationMisconfigured;
use RoundlyConsulting\Auth\Exceptions\AuthException;
use Symfony\Component\HttpFoundation\Response;

->withExceptions(function (Exceptions $exceptions): void {
    // Reshape the rendered response; the status, Cache-Control and Retry-After stay:
    $exceptions->respond(function (Response $response, Throwable $e, Request $request): Response {
        if ($e instanceof AuthException) {
            $response->setContent((string) json_encode(['error' => ['code' => $e->errorCode(), 'message' => $e->getMessage()]]));
        }

        return $response;
    });

    // Or replace the exception before Laravel renders it (misconfiguration left alone):
    $exceptions->map(AuthException::class, fn (AuthException $e): Throwable =>
        $e instanceof AuthenticationMisconfigured ? $e : new ApiProblem($e));
});

Výnimka hostiteľa prenesie všetko, čo by poslal render() balíka:

use Illuminate\Http\JsonResponse;
use RoundlyConsulting\Auth\Exceptions\AuthException;

final class ApiProblem extends RuntimeException
{
    public function __construct(public readonly AuthException $auth)
    {
        parent::__construct($auth->getMessage(), 0, $auth);
    }

    public function render(): JsonResponse
    {
        $extra = $this->auth->extra();   // retry_after, attempts_left, methods
        $headers = ['Content-Type' => 'application/problem+json', 'Cache-Control' => 'no-store, private', 'Pragma' => 'no-cache'];

        if (isset($extra['retry_after'])) {
            $headers['Retry-After'] = (string) $extra['retry_after'];   // 423 and 429
        }

        return new JsonResponse(
            ['type' => $this->auth->errorCode(), 'title' => $this->getMessage(), 'status' => $this->auth->status(), ...$extra],
            $this->auth->status(),
            $headers,
        );
    }

    public function report(): bool
    {
        return true;   // map() also runs when Laravel reports: stay unreported, like the package exception
    }
}

• respond() beží na každej vykreslenej odpovedi vrátane tých, ktoré sa vykreslili samy, a dostane $response, $e a $request. Vidí aj odpovede, ktoré nepochádzajú z balíka, preto sa rozhodujte podľa $e.
• map() sa uplatní aj pri reportovaní výnimky, takže reportuje sa už namapovaná. Nechajte ju nereportovanú (report() vracia true, alebo ju uveďte v dontReport), inak sa vám nástroj na sledovanie chýb zaplní neúspešnými prihláseniami.
• Pri map() vykreslíte všetko sami: status (status()), doplnkové členy (extra(): retry_after, attempts_left, methods), field(), ak klienti čítajú errors, a hlavičky — vždy Cache-Control: no-store, private a pri 423 a 429 Retry-After.
• AuthenticationMisconfigured (a GuardNotConfigured) nemapujte: jej správa uvádza chybný kľúč konfigurácie, render() balíka ju ukáže len pri app.debug a je to jediná výnimka, ktorú balík chce reportovať.
• Ak mapujete na výnimku bez vlastnej metódy render(), vaše callbacky render() ju uvidia — výnimka balíka je jej getPrevious().