Api Key Bundle Laravel Package

Getting Started

This is a Symfony 2 bundle, not a Composer-installable Laravel package. A Laravel dev can't composer require it into an app. Treat it as reference material for building API-key auth, or use it only inside a legacy Symfony 2 codebase.

Minimum steps to stand it up in its native environment:

1. Confirm the stack. You need Symfony ~2.x, friendsofsymfony/user-bundle (FOSUserBundle), and PHP ~5.5+. The last release was 2016-01-14, so anything newer (Symfony 3+/4+/5+) will fight the composer constraints.
2. Install:

   composer require uecode/api-key-bundle
   

3. Register the bundle in app/AppKernel.php:

   new Uecode\Bundle\ApiKeyBundle\UecodeApiKeyBundle(),
   

4. Create an ApiKey entity mapping a key string to a FOSUser user (Doctrine annotations/YAML), and generate a migration.
5. Configure the firewall — set a stateless firewall using the bundle's user provider:

   # app/config/config.yml
   uecode_api_key:
       api_key_entity: AppBundle\Entity\ApiKey
       # header defaults to X-Api-Key
   
   security:
       firewalls:
           api:
               pattern: ^/api
               stateless: true
               uecode_api_key: true
   

6. First use case: protect a JSON API endpoint, issue a key by persisting an ApiKey row tied to a user, and call it with curl -H "X-Api-Key: <key>" https://app/api/me.

First place to look: the bundle's DependencyInjection/ config and its security-listener class. That's where the header name, provider wiring, and lookup behavior live — everything else is Symfony security boilerplate.

Implementation Patterns

• Key issuance is entirely on you. The bundle only authenticates; it does not create keys. Build a console command, admin controller, or service that generates a random key and associates it with a FOSUser user:

  $key = bin2hex(random_bytes(32));
  $apiKey = new ApiKey();
  $apiKey->setKey(hash('sha256', $key)); // store a hash
  $apiKey->setUser($user);
  $em->persist($apiKey); $em->flush();
  // return $key once to the caller
  

• One user, many keys. Model ApiKey with ManyToOne to User, plus label, lastUsedAt, revokedAt, expiresAt. This is how you support rotation and revocation — the bundle won't do it for you.
• Stateless firewall is mandatory. API clients don't hold sessions. Pair the uecode_api_key firewall with stateless: true, and never enable form_login on the same firewall.
• Roles come from FOSUser. Once the key resolves a user, the normal Symfony role voter applies. If you need coarse API scopes, add a scopes column and enforce it in a kernel.request listener or voter rather than in the bundle.
• Testing with an HTTP client:

  curl -i http://localhost:8000/api/orders -H "X-Api-Key: $KEY"
  

  Assert 200 with a valid key, 401 with garbage, and that revoked keys are rejected.
• If you're porting the idea to Laravel, don't port the code — port the pattern:
  • api_keys table: id, user_id, name, key_hash, last_used_at, expires_at, revoked_at.
  • A AuthenticateApiKey middleware that reads X-Api-Key, hashes it, looks up key_hash, checks expiry/revocation, and Auth::login($user).
  • Or skip it and use Sanctum (createToken) if you just need personal access tokens.

Gotchas and Tips

• It's effectively abandoned. Last release 2016, no Symfony 4+/5+ support, and it depends on FOSUserBundle, which itself is deprecated in favor of Symfony's native user system. Do not build new features on this.
• Hard FOSUserBundle dependency. You cannot use it with a plain Doctrine user entity without adapter work. This is the biggest blocker for a Laravel dev reading the docs — the whole user model assumption is Symfony-specific.
• Keys are stored as you store them. The bundle doesn't hash or salt. Store a hash and compare in constant time; treat the raw key as show-once.
• No built-in expiry, rotation, revocation, or rate limiting. All of that is your application's job. Plan for it on day one or you'll ship long-lived, unrevokable keys.
• Header name is configurable (X-Api-Key by default), but the listener runs early in the firewall chain. If auth silently fails, check: (1) the firewall pattern matches the URL, (2) the firewall is marked stateless, (3) the user provider points at the right entity/property, (4) the security listener priority hasn't been displaced by another bundle.
• Debugging a 401: enable security.firewalls.api logging, drop a temporary listener at kernel.request to dump the resolved user, and verify the Doctrine query actually hits an ApiKey row. Most 401s are a misconfigured provider property or a trailing \r\n in the header from a sloppy client.
• Extension points: override the ApiKey entity and the security factory if you need custom lookup. Everything else (header name, provider) is config. There's very little surface area, which is why the bundle is small — and why you'll be writing most of the meaningful logic yourself.
• For a Laravel dev evaluating "do I need this": you don't. The equivalent is ~80 lines of middleware + a migration, or Sanctum/Passport. Use this package as a checklist of what API-key auth must include (hashing, revocation, expiry, per-user keys), not as a dependency.