Search by

itmosoft / laravel-api-keys

adeelrao007

Secure, scoped API key management for Laravel applications, with hashed secrets, expiration, revocation, and usage tracking.

Package info

github.com/ITMOSOFT/laravel-api-keys

pkg:composer/itmosoft/laravel-api-keys

Statistics

Installs: 1

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v1.0.0 2026-11-17 10:42 UTC

This package is auto-updated.

Last update: 2026-11-17 10:43:06 UTC


README

Secure API key management for Laravel applications. Secrets are generated using PHP's cryptographically secure random generator, stored only as SHA-256 hashes, and can be scoped, expired, revoked, and usage-tracked.

Requirements

  • PHP 8.3+
  • Laravel 12 or 13

Installation

composer require itmosoft/laravel-api-keys
php artisan vendor:publish --tag=itmosoft-api-keys-config
php artisan vendor:publish --tag=itmosoft-api-keys-migrations
php artisan migrate

The service provider is registered through Laravel package discovery.

Create an API key

use ItmoSoft\ApiKeys\Services\ApiKeyManager;

$credential = app(ApiKeyManager::class)->create(
    owner: $user,
    name: 'Warehouse integration',
    abilities: ['products:read', 'inventory:update'],
    expiresAt: now()->addDays(90),
);

// Display this secret once. Do not log or persist it in plaintext.
return [
    'key' => $credential->plainTextKey,
    'id' => $credential->apiKey->id,
];

The plaintext key is returned only at creation time. The database stores its SHA-256 hash, not the secret.

Protect routes

Route::middleware(['api-key', 'api-key.abilities:products:read'])->get(
    '/integration/products',
    fn (Request $request) => ProductResource::collection(Product::all())
);

By default, the package accepts the X-API-Key header. Bearer tokens are also accepted when allow_bearer_token is enabled.

For a route requiring more than one ability, list all required abilities. Every listed ability must be present:

Route::middleware(['api-key', 'api-key.abilities:orders:read,orders:export'])
    ->get('/integration/orders/export', ExportOrdersController::class);

The authenticated model is available on the request:

$apiKey = request()->attributes->get('itmosoft_api_key');
$owner = $apiKey?->owner;

Revoke a key

app(ApiKeyManager::class)->revoke($apiKey);

Or call $apiKey->revoke() directly.

Validate a key manually

$apiKey = app(ApiKeyManager::class)->authenticate($plainTextKey);

if (! $apiKey) {
    // Invalid, expired, or revoked.
}

Configuration

Published config: config/itmosoft-api-keys.php.

Setting Default Purpose
table api_keys Database table
header X-API-Key Request header
allow_bearer_token true Also read Authorization: Bearer
prefix its_ Visible key prefix
secret_bytes 32 Random secret bytes (minimum 16)
default_abilities ['*'] Abilities used when none are supplied
track_last_used true Update last-used timestamp

Security notes

  • Keys are high-entropy random values; only SHA-256 hashes are persisted.
  • Show the plaintext secret only once and deliver it through a secure channel.
  • Use least-privilege abilities rather than * for integrations.
  • Use HTTPS. Do not put API keys in URLs, browser code, analytics, or logs.
  • Rotate keys after suspected exposure and revoke unused keys.
  • The middleware authenticates the integration key; your application must still enforce resource-level authorization and tenant boundaries.
  • If allow_bearer_token is enabled, avoid ambiguity with other bearer-token authentication on the same route group.

Scope and limitations

This package provides API key issuance, authentication, abilities, expiry, revocation, and last-used tracking. It does not implement OAuth2, JWT, customer login, rate limiting, IP allowlists, key quotas, key-rotation grace periods, or webhook signature verification. It does not automatically authorize access to a particular tenant's records; enforce ownership and tenant isolation in your application.

Testing

composer install
composer test

License

MIT. See LICENSE.