- How do I install and set up ejarnutowski/laravel-api-key in a Laravel app?
- Install it with Composer, and the service provider is auto-discovered so no manual registration is needed. Run vendor:publish to pull out the config file and the migration, then run your migrations to create the API keys table. Add the HasApiKeys trait to the model that should own keys (typically User), and attach the auth.apikey middleware alias to the route group you want to protect. A working proof of concept is realistically a sub-one-day job.
- How do I protect routes with the API key middleware?
- The package registers route middleware that validates an incoming credential against stored keys and lets the request through when it matches. You apply it to a route group, for example wrapping your API routes with the auth.apikey alias. It is not an authentication guard, so it does not register a guard driver or change how Laravel resolves the current user.
- Does the package read the key from a header or a query parameter?
- It accepts an X-Api-Key header, and it also supports passing the key as a query parameter. The header is the better choice for production because query strings end up in access logs, proxy logs, and browser history. Confirm the exact parameter name in the published config before wiring clients.
- Are API keys stored hashed in the database, and is comparison timing-safe?
- This is the single most important thing to verify before adopting the package, because the TPM assessment flags it as unresolved. Read the source and check the migration and validation path: if keys are persisted in plaintext, that is a disqualifier for anything touching regulated or customer data. Also confirm whether comparison is constant-time rather than a naive string equality check. If either answer is wrong for your threat model, plan on a fork with hashed storage.
- Does laravel-api-key populate Auth::user() or integrate with Gates and Policies?
- No. The package is a credential verifier, not an identity system: it validates the key and lets the request proceed, but it does not set the authenticated user or register a guard. As a result, Gates, Policies, and anything that depends on Auth::user() will not see a caller identity out of the box. If you need per-key authorization, you must resolve the owning model yourself and build the authorization layer on top.
- How does this compare to Laravel Sanctum or Passport?
- Sanctum and Passport are the right tools for first-party user authentication, mobile sessions, OAuth flows, and delegated scopes, and Sanctum is maintained by the Laravel team. This package targets a narrower problem: service-to-service calls, webhook verification, partner or tenant integrations, and early-stage product APIs where a bearer-style key is the contracted auth model. Treat it as a thin, cheap solution for that narrow case, not a replacement for Sanctum.
- Does it support scopes, per-key rate limiting, or audit logging?
- Not built in. The package has no scopes or permissions, no per-key rate limiting, no rotation grace periods, and no audit logging. You can layer these on yourself using Laravel's rate limiter and your own schema columns, but budget for that work up front rather than assuming the package covers it.
- Can a user have multiple active API keys for zero-downtime rotation?
- Because keys are attached through the HasApiKeys trait, a model can own more than one key at a time, which makes overlapping rotation feasible. What is missing is any built-in rotation workflow such as grace periods, expiry, or automatic revocation. Implement issue-new, migrate-clients, revoke-old as explicit operations in your own service layer.
- Which Laravel and PHP versions does this package support?
- Check the composer constraints in the repository against your target Laravel major before committing to anything. If your app runs a newer Laravel than the package declares, your options are pinning the framework (usually unacceptable), forking and patching the package (which turns a dependency into owned code), or skipping it. Declared support and actually-tested support are not always the same, so run a spike against your real version.
- Is it safe to use in production, and what is the maintenance risk?
- The main risk is maintenance posture: a small single-maintainer package with modest star count is a candidate for abandonment, and there is no vendor SLA. Laravel version bumps will eventually break it. Mitigate by wrapping issuance, validation, and revocation behind an internal ApiKeyService interface, publishing and owning the config and migration, and never letting domain code depend on the package trait directly. That keeps a later swap to Sanctum a data migration rather than a rewrite.