Add stateless API starter kit by WendellAdriel · Pull Request #78 · laravel/maestro

WendellAdriel · 2026-04-15T18:03:57Z

Overview

Maestro ships starter kits for every flavor of Laravel app, but there was no option for teams building a pure JSON API. This adds a new API variant so backend-only projects can start from the same orchestrated foundation as the Inertia and Livewire kits.

About the Kit

The kit is stateless and built on Sanctum, with endpoints for register, login, logout, current user, profile and password updates, email verification, token refresh, and account deletion. It also uses JSON:API resources.

Scramble generates the API docs and serves them at /docs using Scalar. Account deletion and password updates are gated behind the verified middleware to match the Fortify kits, while profile edits stay open so unverified users can fix a bad email.

Orchestrator Updates

Orchestrator support comes along with it: BuildCommand, the StarterKit enum, the kit manifest, and the check/kit helpers all learn about the new variant, and CI plus the push workflow now include API in the matrix.

The README, CLAUDE.md, AGENTS.md, and SKILL.md were updated to reflect the new variant count (22) and the --api flag.

pushpak1300

LGTM !

joetannenbaum

This is looking really good! Just a couple of notes.

joetannenbaum · 2026-05-15T13:14:19Z

+
+        event(new Registered($user));
+
+        return response()->json([


Why aren't we returning a user resource here along with the token?

I don't think that's needed, TBH.
We already have the /me endpoint for getting the user info.

Hm, not sure I agree here. I can get on board with that for login, but for register why don't we just do something like this? Reduces round trips and gives the client the information they definitely need anyway.

(new UserResource($user)) ->additional(['token' => $token]) ->response() ->setStatusCode(Response::HTTP_CREATED);

joetannenbaum · 2026-05-15T13:31:05Z

+        );
+
+        if ($user->hasVerifiedEmail()) {
+            return response()->json(['message' => __('Email already verified.')]);


Might be overkill, but do we want to macro message, successMessage, etc? Or too much?

That might be a good idea.
I'll try it out so we can check how it will look like

Hey @joetannenbaum

I think this is a good idea to extract into a helper, because it's something that can be heavily used in the codebase when starting to implement something with the Starter Kit, however, I think the macro is not the best solution. Because it can be a little confusing, and depending on what devs are using, they may not even get autocomplete for it.

I think we can do it in either of these ways:

A response class implementing the Illuminate\Contracts\Support\Responsable interface

A trait - HasApiResponses (or something similar) - with a method messageResponse (or something similar)

Let's go with response class, makes for better extendibility.

joetannenbaum · 2026-05-15T14:19:10Z

+            ]);
+        }
+
+        $token = $user->createToken('auth')->plainTextToken;


Do we want to give them the opportunity to name this in case they want to list tokens and identify them? Like an optional device_name field with the auth fallback value?

By default, I think we can use this auth, and if people need they can extend it, what do you think?

I dunno, seems pretty cheap to just do something like $request->string('device_name', 'auth'), why not?

joetannenbaum

Added some responses to our current conversations.

Two additional things:

We're mixing JsonApiResource and flat JSON responses, feels funny. We should go one or the other, yeah? Or, probably worse idea, allow the user to choose the format at installation time?
I think we talked about it and may have tabled it, but should we offer/scaffold anything around versioning in the kit?

RasmusPJustesen · 2026-06-04T09:20:43Z

Exciting to see this as ready for review! ⭐

WendellAdriel · 2026-06-04T09:25:15Z

@RasmusPJustesen we're getting there! 🚀

BuildCommand, StarterKit enum, kit-manifest, check-kits, and kit-helpers updated to handle the new API kit. GitHub Actions workflows include the API variant in test and push matrices. README, CLAUDE.md, AGENTS.md, and SKILL.md reflect the new variant count (22) and --api flag.

Ships kits/API/Base, a stateless JSON API layer on top of Shared/Blank and Shared/Base. - Sanctum auth flow: register, login (rate limited), logout, current user - Profile and password updates as PATCH endpoints - Email verification with signed URLs and resend notification - JSON:API-style responses via a single UserResource - Scribe-driven docs configured entirely with PHP attributes - Response messages wrapped in __() so kits can localize them - Feature tests covering every endpoint plus Unit/Feature ExampleTests

- Add DELETE /user account deletion endpoint requiring the current password; tokens and user are removed inside a transaction - Add POST /token/refresh to rotate the current Sanctum token - Drop the /api URL prefix and redirect / to /up - Give every API route an explicit name and migrate tests to route() helpers - Wrap register and refresh DB writes in transactions; dispatch the Registered event after commit

Mirror the Inertia/Livewire Fortify kits: unverified users can still log in, view, and update their profile (to fix their email), but cannot delete their account or change their password. Adds two regression tests that skip when MustVerifyEmail is not enabled.

Without this file, the watcher in orchestrator/scripts/watch.js had no source of vendor/node_modules ignore patterns for the API layer stack and would sync build/vendor/** back into kits/API/Base on live change events.

Allow signed API verification links to succeed without a bearer token while keeping API-only matrix runs separate from Fortify variants. Made-with: Cursor

- Throttle the register endpoint at 5/min to match login - Validate the verify-email hash before exposing already-verified state, closing the unauthenticated account-probe vector - Preserve the original token name and abilities on refresh instead of resetting both to 'auth' and ['*'] - Use fluent Rule::unique(User::class) in RegisterRequest for parity with ProfileUpdateRequest - Use Tests\TestCase in tests/Unit/ExampleTest so the unit suite uses the kit's bootstrap

WendellAdriel requested a review from joetannenbaum April 15, 2026 18:08

WendellAdriel force-pushed the feat/api-starter-kit branch from 41c3dcd to c73b048 Compare April 22, 2026 16:36

pushpak1300 self-requested a review April 24, 2026 09:38