Voyti

Stateless Client

A stateless REST API for any client that can hold a bearer token, a browser-based single-page application (SPA) foremost among them, built on voyti-api’s bearer-token infrastructure: credential login/logout, self-registration, password reset, own-profile and own-sessions management, plus admin RBAC and audit-log endpoints.

Response messages are translatable. A consumer picks the language with a standard Accept-Language request header; voyti-api’s LocaleMiddleware matches it against the installed catalogs and falls back to ApiConfig::$defaultLocale if nothing matches.

Installation

Authentication

POST v1/auth/login verifies a username/email + password and returns {"status": "ok", "token": "..."} - a bearer token for the same Authorization: Bearer <token> scheme voyti-api uses everywhere else. It replicates the exact event sequence core’s SessionController::login() dispatches (BeforeLoginEvent/FailedLoginEvent/AfterLoginEvent), so voyti-lockout and audit-log/session listeners work unmodified regardless of whether a login came from the HTML app or this API. If the account has 2FA enabled, login instead returns a challenge - see below.

Public

Authenticated

Admin

RBAC mirrors core’s HTML admin screen: {itemType} is role or permission. Per-user assignment management is a separate sub-resource, not a property of the item itself: update diffs the submitted userIds against the current assignment list, removing and adding as needed, and rejects any ID that doesn’t match an existing user.

Two-factor authentication

When voyti-2fa is installed, a login for an account with 2FA enabled returns a challenge instead of a token:

{ "status": "challenge_required", "challengeToken": "...", "method": "totp", "isCodeBased": true, "expiresIn": 300 }

Submit the code (or a backup code, or a WebAuthn-style payload/domain pair for client-collected methods) along with the challengeToken to receive the real bearer token:

Enrollment and management are also available - enabling/disabling a code-based method and regenerating backup codes, mirroring the same re-authentication rule as the HTML settings page. Enable returns a fresh set of backup codes directly in the response, since a JSON caller has no follow-up reveal page to redirect to:

A code-based method’s own setup step must run first, or enable has nothing to verify a submitted code against - mirroring each package’s HTML setup screen. When voyti-2fa-totp is installed, setup/renew issue the QR code and secret; setup reuses the account’s existing secret, renew always issues a fresh one. When voyti-2fa-email is installed, send-code emails a fresh code (never returned in the response - only the mailer sees it):

Registering a client-collected method (WebAuthn) isn’t done through the generic action above - it runs through its own dedicated ceremony. When voyti-2fa-webauthn is installed, the pending challenge normally kept in the session is instead persisted on the account’s own (not-yet-enabled) two-factor row between the two requests, since a bearer-token caller has no session continuity across them:

GDPR

When voyti-gdpr is installed, self-service data export and account anonymization become available, delegating to that package’s own GdprExportService and AnonymizeUserService:

Social login

When voyti-social-auth is installed, a popup-based OAuth2 flow becomes available. Unlike the HTML app’s social login, this doesn’t establish a session in the SPA itself - the popup completes the provider round-trip, then redirects to redirectUrl with a short-lived, single-use code rather than the bearer token directly, so the token never ends up in a URL or browser history entry:

// params.php
return [
    'yiirocks/voyti' => [
        'api' => [
            'social' => [
                'redirectUrl' => 'https://spa.example.com/oauth-callback',
            ],
        ],
    ],
];

Only the guest-login path is supported: connecting a social account to an already-authenticated user, and completing a “pending” account link that needs manual registration first, both require request context this stateless popup callback doesn’t have. Either case is reported to the SPA as an error query parameter instead.