Authlete Laravel Laravel Package

Getting Started

1. Install the wrapper and the SDK it depends on.

   composer require authlete/authlete-laravel
   

   The Laravel package is a thin service-provider wrapper around authlete/authlete-php. Almost everything you actually call (AuthleteApi, request/response DTOs, Action enum) comes from the underlying SDK, so install/read that one too.

2. Publish and open the config first.

   php artisan vendor:publish --provider="Authlete\Laravel\AuthleteServiceProvider"
   

   Look at config/authlete.php. It exposes the three values you must supply via .env:

   AUTHLETE_BASE_URL=https://us.authlete.com   # region-specific
   AUTHLETE_SERVICE_API_KEY=...
   AUTHLETE_SERVICE_API_SECRET=...
   

   If the env var names differ in your published copy, trust the file over the README.

3. Resolve AuthleteApi from the container. The wrapper's only real job is binding the SDK client as a singleton:

   use Authlete\Api\AuthleteApi;
   
   public function __construct(private AuthleteApi $authlete) {}
   

4. First real use case: prototype the /authorize endpoint. In a controller, translate the incoming Illuminate\Http\Request into an AuthorizationRequest, call $this->authlete->authorization($req), then switch on $response->getAction(). Authlete does all OAuth/OIDC protocol validation for you — you own routing, UI, and session state.

That's the whole onboarding loop: config → bind → implement one protocol endpoint → branch on Action.

Implementation Patterns

One controller per protocol endpoint. Authlete expects you to own the HTTP routes and delegate the protocol logic:

Route::get('/authorize', [AuthorizationController::class, 'handle']);
Route::post('/token', [TokenController::class, 'handle']);
Route::post('/introspect', [IntrospectionController::class, 'handle']);
Route::post('/revoke', [RevocationController::class, 'handle']);
Route::get('/userinfo', [UserInfoController::class, 'handle']);
Route::get('/jwks', [JwksController::class, 'handle']);

Always branch on Action, not HTTP status. Every Authlete response is a small state machine. The recurring pattern:

$res = $this->authlete->authorization($authRequest);

switch ($res->getAction()) {
    case 'OK':       // render your login/consent UI, carry $res->getTicket()
    case 'LOCATION': return redirect($res->getResponseContent());
    case 'FORM':     // render an auto-submitting HTML form
    case 'JSON':     return response($res->getResponseContent())
                        ->header('Content-Type', 'application/json');
    case 'NO_CONTENT':
    case 'BAD_REQUEST':
        // map to 400 + JSON body
}

For /token, /introspect, /revoke, and /userinfo, the pattern is narrower: you almost always end in a JSON action and can pipe getResponseContent() straight back with application/json.

Ticket pattern for multi-step UI. If you split consent into a screen, call authorization() again with the ticket after the user decides. Keep tickets in the session or a short-TTL cache — never trust a client-echoed ticket.

Protect resources with introspection. For API routes, add middleware that reads the Authorization: Bearer token and calls $this->authlete->introspection(...); reject on active === false. Cache positive results for the token's remaining TTL.

Bind a fake AuthleteApi in tests — this is the cleanest integration point the package gives you:

$this->app->instance(AuthleteApi::class, $this->createMock(AuthleteApi::class));

Feature-test your controllers end-to-end without hitting Authlete.

Compose with Laravel features, don't fight the wrapper: Route::middleware('throttle:token') on /token, form-request validation for required query params before touching Authlete, and a dedicated config('authlete') log channel for debugging.

Gotchas and Tips

• The package is a binding, not a framework. 42 stars, zero dependents — expect no middleware, routes, or opinionated structure. When docs feel thin, jump straight to authlete/authlete-php and the Authlete REST API docs; method names on AuthleteApi mirror the REST paths.
• Base URL is region-specific. us.authlete.com, jp.authlete.com, eu.authlete.com are not interchangeable — a wrong base URL typically returns 401s that look like bad credentials, not bad routing.
• Action values are plain strings on the SDK response objects, not a Laravel-aware enum. Add a match or a small helper to map them to responses, otherwise you'll sprinkle raw string comparisons everywhere.
• Never log the API secret or raw getResponseContent() for /token — it contains access/refresh tokens. Log request IDs and actions instead.
• Catch AuthleteApiException (network / 5xx from Authlete) at the controller boundary and translate to a 502 or 500 — do not surface Authlete's raw error body to clients.
• Config caching bites during tuning. After editing config/authlete.php, run php artisan config:clear; the singleton captures credentials at boot.
• Extension point: subclass and rebind. If you need retries, a Guzzle middleware, or a tracing header, extend the SDK client, override the constructor/HTTP transport, and rebind AuthleteApi in your own AppServiceProvider after the package provider.
• Watch the PHP/Laravel version constraints in composer.json before adopting — the SDK's transitive Guzzle/PHP requirements are the usual source of resolution conflicts in older apps.
• Version-pin the SDK alongside the wrapper. Bumping authlete/authlete-php independently can break response DTOs your controllers depend on; treat them as a pair.