laravel-api-keys maintained by itmosoft
ITMOSOFT Laravel API Keys
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_tokenis 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.