Skip to content

Route Publishing ​

Configure and publish authentication routes in app/Config/Routes.php.

NOTE

jengo/auth does not publish all routes by default. You can publish only the exact features your application requires using dedicated helper methods or selective flow registration.


1. Feature Suites (Dedicated Helpers) ​

The recommended way to publish routes is using dedicated feature helper methods on RouteRegistrar or the auth() helper:

php
// app/Config/Routes.php
use Jengo\Auth\Support\RouteRegistrar;

// 1. Core Authentication (login, logout, registration, password reset) -> [API Reference](./api-reference#1-core-authentication)
RouteRegistrar::core($routes);

// 2. Post-Auth MFA / Action Pipeline (show, challenge/resend, handle, cancel) -> [Actions Guide](./actions)
RouteRegistrar::action($routes);

// 3. Passwordless Magic Link Login & Verification -> [API Reference](./api-reference#2-passwordless-magic-links)
RouteRegistrar::magicLink($routes);

// 4. Two-Factor Authentication Settings & Enrollment (TOTP, Passkeys) -> [2FA Guide](./two-factor)
RouteRegistrar::twoFactor($routes);

// 5. Sudo Mode (Step-up privileged re-authentication) -> [Sudo Guide](./sudo)
RouteRegistrar::sudo($routes);

// 6. Personal Access Tokens API Management -> [Guards & Tokens](./guards#token-prefix--formatting)
RouteRegistrar::tokens($routes, [
    'prefix' => 'api/v1/auth/tokens',
    'filter' => 'auth:token',
]);

// 7. Social / OAuth2 Sign-In (redirect & callback) -> [Social Guide](./social)
RouteRegistrar::social($routes);

// 8. Password Provisioning / Set Password -> [Social Guide](./social#5-password-provisioning-workflow)
RouteRegistrar::setPassword($routes);

// 9. Publish All Features
RouteRegistrar::all($routes);

You can also call these directly via auth() or service('auth'):

php
auth()->coreRoutes($routes);        // Core authentication
auth()->actionRoutes($routes);      // Post-auth action pipeline (MFA)
auth()->magicLinkRoutes($routes);   // Passwordless magic links
auth()->twoFactorRoutes($routes);   // Multi-factor management
auth()->sudoRoutes($routes);        // Sudo privileged step-up mode
auth()->tokenRoutes($routes);       // Scoped Personal Access Tokens
auth()->socialRoutes($routes);      // Social / OAuth2 routes
auth()->setPasswordRoutes($routes); // Password provisioning routes

2. Advanced Customization & Global Configuration ​

You can configure options globally across all route helper calls with RouteRegistrar::configure(), or pass $options per method call:

php
// app/Config/Routes.php
use Jengo\Auth\Support\RouteRegistrar;

// 1. Global Default Configuration
RouteRegistrar::configure([
    'prefix' => 'auth',
    'paths'  => [
        'login'    => 'sign-in',
        'logout'   => 'sign-out',
        'register' => 'join',
    ],
]);

// 2. Per-Registration Options (merged with global defaults)
RouteRegistrar::core($routes, [
    'logoutMethod' => 'post', // 'post' (default) or 'get'
    'controllers'  => [
        'login'    => \App\Controllers\CustomLoginController::class,
    ],
    'filters'      => [
        'register' => ['honeypot'],
    ],
]);

3. Selective Flow Registration (only / except) ​

When using RouteRegistrar::routes($routes, $options) or auth()->routes($routes, $options), you can selectively filter which flow suites are published using the only and except options:

php
// Register only specific flows
RouteRegistrar::routes($routes, [
    'only' => ['login', 'register', 'password-reset'],
]);

// Or exclude specific flows
RouteRegistrar::routes($routes, [
    'except' => ['magic-link', 'tokens'],
]);

4. Flow Identifier Reference Table ​

Below is the complete list of flow names available for only and except, along with their registered HTTP endpoints, canonical route names, and default controllers:

Flow NameHTTP VerbDefault PathCanonical Route Name (as)Default Controller Action
loginGETloginloginLoginController::showLogin
POSTloginlogin.attemptLoginController::attemptLogin
POST / GETlogoutlogoutLoginController::logout
registerGETregisterregisterRegisterController::showRegister
POSTregisterregister.attemptRegisterController::attemptRegister
password-resetGETforgot-passwordforgot-passwordForgotPasswordController::showForgot
POSTforgot-passwordforgot-password.sendForgotPasswordController::sendResetLink
GETreset-password/(:segment)reset-passwordResetPasswordController::showReset
GETreset-passwordreset-password.queryResetPasswordController::showReset
POSTreset-passwordreset-password.attemptResetPasswordController::attemptReset
magic-linkGETmagic-linkmagic-linkMagicLinkController::showMagicLink
POSTmagic-linkmagic-link.sendMagicLinkController::sendLink
GETmagic-link/verify/(:segment)magic-link.verifyMagicLinkController::verifyLink
GETmagic-link/verifymagic-link.verify.queryMagicLinkController::verifyLink
actionGETaction/showauth.action.showActionController::show
POSTaction/challengeauth.action.challengeActionController::challenge
POSTaction/handleauth.action.handleActionController::handle
POSTaction/cancelauth.action.cancelActionController::cancel
GETaction/cancelauth.action.cancel.getActionController::cancel
sudoGETsudoauth.sudoSudoController::index
POSTsudo/challengeauth.sudo.challengeSudoController::challenge
POSTsudo/verifyauth.sudo.verifySudoController::verify
POSTsudo/exitauth.sudo.exitSudoController::exit
two-factorGETtwo-factortwo-factor.indexTwoFactorSettingsController::index
POSTtwo-factor/enroll/starttwo-factor.enroll.startTwoFactorSettingsController::startEnrollment
POSTtwo-factor/enroll/confirmtwo-factor.enroll.confirmTwoFactorSettingsController::confirmEnrollment
POSTtwo-factor/unenrolltwo-factor.unenrollTwoFactorSettingsController::unenroll
tokensGETtokenstokens.indexTokenController::index
POSTtokenstokens.createTokenController::create
POSTtokens/createtokens.create.namedTokenController::create
DELETEtokens/(:segment)tokens.revokeTokenController::revoke
POSTtokens/revoke/(:segment)tokens.revoke.postTokenController::revoke
socialGEToauth/(:segment)auth.oauth.redirectOAuthController::redirect
GEToauth/callback/(:segment)auth.oauth.callbackOAuthController::callback
set-passwordGETset-passwordauth.password.set.viewSetPasswordController::showSetPassword
POSTset-passwordauth.password.setSetPasswordController::attemptSetPassword

5. Route Options Reference ​

The $options parameter accepts the following configuration keys:

Option KeyTypeDefaultDescription
prefix / groupstring""Global URL prefix to wrap the published routes inside a CodeIgniter group (e.g. 'auth' or 'api/v1/auth').
groupOptionsarray[]Additional CI4 route group options (such as ['filter' => '...'], ['subdomain' => '...']).
onlyarray[]Explicit array of flow names to register.
exceptarray[]Explicit array of flow names to exclude.
pathsarray[]Associative array overriding endpoint slugs (e.g. ['login' => 'sign-in', 'register' => 'signup']).
controllersarray[]Associative array replacing the default controller classes per flow (e.g. ['login' => CustomLoginController::class]).
filtersarray[]Associative array applying route-specific filters (e.g. ['register' => ['honeypot'], 'login' => ['throttle:5,1']]).
logoutMethodstring'post'HTTP verb for logout. Set to 'get' to enable GET /logout instead of POST.
allowGetLogoutboolfalseConvenience flag. Setting true sets logoutMethod to 'get'.

6. Resolving Named Routes with url_to() and auth_url() ​

All route names (as) are canonical and standardized. Even when you customize paths or add prefixes, you can reliably resolve URLs across your application using url_to() or auth_url():

php
// In Views, Controllers, or Modifiers:
$loginUrl  = url_to('login');
$mfaUrl    = url_to('auth.action.show');
$cancelUrl = url_to('auth.action.cancel');
$resendUrl = url_to('auth.action.challenge');
$resetUrl  = url_to('reset-password', $token);

// auth_url() helper provides graceful fallbacks:
$profile2fa = auth_url('two-factor.index');

7. Configuring Redirect Destinations ​

In app/Config/Auth.php, configure post-authentication destinations using URL paths (for landing pages) or canonical route names (for authentication flows):

php
namespace Config;

use Jengo\Auth\Config\Auth as BaseAuth;

class Auth extends BaseAuth
{
    /**
     * Redirect destinations.
     * Use URL paths (e.g. '/', '/dashboard') for landing pages or route names (e.g. 'login') for authentication targets.
     */
    public array $redirects = [
        'login'          => '/dashboard', // Landing page after login
        'register'       => '/welcome',   // Landing page after registration
        'logout'         => 'login',      // Named route or URL path after logout
        'password_reset' => 'login',      // Named route or URL path after password reset
        'magic_link'     => '/dashboard', // Landing page after magic link login
        'action'         => '/dashboard', // Landing page after completing MFA/action
        'sudo'           => '/settings',  // Landing page after sudo mode verification
        'denied'         => 'login',      // Named route or URL path when access is denied
    ];
}

When resolving redirects internally or in custom modifiers, use auth_redirect_url($key, $default):

php
// Resolves directly to '/dashboard'
$url = auth_redirect_url('login', '/');

// Resolves dynamically to the named route URL (e.g. 'https://example.com/sign-in')
$url = auth_redirect_url('logout', 'login');

Released under the MIT License.