Credential Stuffing in Laravel with Api Keys

Credential stuffing is an automated attack where previously breached username and password pairs are systematically attempted against a login endpoint to exploit password reuse. In Laravel, coupling credential stuffing with API keys can unintentionally expose two distinct attack surfaces: the traditional web authentication flow and token-based API access.

When API keys are used as bearer tokens for authentication (e.g., via sanctum or custom guard configurations), they are often stored client-side or embedded in JavaScript, mobile apps, or CI scripts. If these keys are accidentally leaked in public repositories, logs, or client-side code, they become high-value targets. An attacker running a credential stuffing campaign may incorporate leaked API keys to test whether those keys are reused across services or combined with weak account passwords. This is particularly risky when API keys are treated as long-lived credentials without rotation or binding to IP/context.

Laravel’s default authentication guards and session management are designed for user credentials, not for long-lived API keys. If developers map API keys to users via relationships like User::apiKey() without additional safeguards, an attacker who obtains a valid key can pivot to impersonate the associated user. Moreover, if rate limiting is not enforced per API key or per user, automated stuffing tools can probe many keys and associated user accounts without triggering defenses. The risk is compounded when key validation does not enforce scope, expiration, or context checks, allowing a key obtained via stuffing or leakage to access sensitive endpoints unchecked.

Another subtle vector involves logging and error messages. Verbose errors in Laravel can reveal whether a key exists in the system (e.g., 'Token not found' vs 'Token invalid'), aiding attackers in refining stuffing lists. Additionally, if API key validation occurs after partial user authentication (e.g., in middleware stacks), attackers may chain stolen credentials with valid keys to bypass intended restrictions.

Mitigating credential stuffing risks when using API keys in Laravel requires tightening how keys are issued, stored, validated, and rotated. Below are concrete, secure patterns with syntactically correct code examples.

1. Use Laravel Sanctum with hashed keys and strict guard configuration

Sanctum provides a secure way to manage API tokens. Ensure tokens are hashed at rest and bound to a user and optional abilities.

// Create a token with abilities and expiration
use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens, HasFactory, Notifiable;
}

// In a controller or service
public function issueToken(Request $request)
{
    $request->validate([
        'email' => 'required|email',
        'password' => 'required',
        'device_name' => 'required|string',
    ]);

    if (!Auth::attempt($request->only('email', 'password'))) {
        return response()->json(['message' => 'Invalid credentials'], 401);
    }

    $token = $request->user()->createToken(
        $request->device_name,
        ['api:read', 'api:write'],
        now()->addDays(30) // short-lived token
    );

    return response()->json(['token' => $token->plainTextToken]);
}

2. Hash API keys in the database and avoid exposing raw keys

Never store raw API keys. Use Laravel’s hashing via a cast or accessor/mutator so that only the hashed version resides in storage.

// In your migration
Schema::create('api_keys', function (Blueprint $table) {
    $table->id();
    $table->foreignId('user_id')->constrained()->onDelete('cascade');
    $table->string('hashed_key')->unique();
    $table->string('plain_text_key')->nullable(); // only for initial display
    $table->json('abilities')->nullable();
    $table->timestamp('expires_at')->nullable();
    $table->timestamps();
});

// When verifying a key in middleware or a guard
class ApiKeyUserProvider implements UserProvider
{
    public function validateCredentials(User $user, array $credentials)
    {
        return Hash::check($credentials['raw_key'], $user->hashed_key);
    }
}

3. Enforce scope, context, and rotation; add rate limiting per key

Bind keys to usage constraints and enforce rate limits to blunt stuffing attempts that rely on key reuse.

// Middleware to check scope and expiration
class EnsureApiKeyHasScope
{
    public function handle($request, Closure $next, string $requiredScope)
    {
        $key = $request->bearerToken();
        $apiKey = DB::table('api_keys')->where('hashed_key', hash('sha256', $key))->first();

        if (! $apiKey) {
            return response()->json(['error' => 'Unauthorized'], 401);
        }

        if (now()->gt($apiKey->expires_at)) {
            return response()->json(['error' => 'Token expired'], 401);
        }

        $scopes = json_decode($apiKey->abilities, true);
        if (! in_array($requiredScope, $scopes)) {
            return response()->json(['error' => 'Insufficient scope'], 403);
        }

        return $next($request);
    }
}

// In routes/api.php
Route::middleware(['auth:sanctum', 'scope:api:read'])->get('/profile', fn (Request $request) => $request->user());

// Rate limiting by key (in RouteServiceProvider or via middleware)
RateLimiter::for('api-key', function (Request $request) {
    return Limit::perMinute(60)->by($request->bearerToken() ?: $request->ip());
});

4. Rotate keys and audit usage; avoid long-lived static keys

Implement key rotation and monitor usage patterns. When rotating, invalidate previous keys and notify users. This reduces the window of opportunity for keys compromised via stuffing or leaks.

// Rotate key endpoint example
public function rotateKey(Request $request)
{
    $request->user()->currentAccessToken()?->delete();
    $newToken = $request->user()->createToken(
        $request->user()->currentDeviceName(),
        $request->user()->getAbilities(),
        now()->addDays(30)
    );
    return response()->json(['token' => $newToken->plainTextToken]);
}