nowo-tech / api-token-bundle
Personal API tokens for Symfony: hashed lookup tokens with per-module grants, a tenant reach, mandatory expiry, revocation, rate limits and audit events, one Bearer authenticator for every API and a UiKit account and operator UI.
Package info
github.com/nowo-tech/ApiTokenBundle
Type:symfony-bundle
pkg:composer/nowo-tech/api-token-bundle
Fund package maintenance!
Requires
- php: >=8.2 <8.6
- doctrine/dbal: ^4.0
- doctrine/orm: ^3.3
- doctrine/persistence: ^3.4 || ^4.0
- nowo-tech/transaction-contract: ^1.0
- nowo-tech/transaction-doctrine: ^1.6
- psr/clock: ^1.0
- psr/event-dispatcher: ^1.0
- psr/log: ^2.0 || ^3.0
- symfony/clock: ^7.4 || ^8.0
- symfony/config: ^7.4 || ^8.0
- symfony/console: ^7.4 || ^8.0
- symfony/dependency-injection: ^7.4 || ^8.0
- symfony/event-dispatcher: ^7.4 || ^8.0
- symfony/http-kernel: ^7.4 || ^8.0
- symfony/security-core: ^7.4 || ^8.0
- symfony/service-contracts: ^3.5
- symfony/uid: ^7.4 || ^8.0
Requires (Dev)
- doctrine/doctrine-bundle: ^2.13 || ^3.0
- friendsofphp/php-cs-fixer: ^3.0
- igor-php/igor-php: ^0.10.1
- nowo-tech/phpstan-frankenphp: ^1.3
- phpstan/extension-installer: ^1.4
- phpstan/phpstan: ^2.0
- phpstan/phpstan-phpunit: ^2.0
- phpstan/phpstan-symfony: ^2.0
- phpunit/phpunit: ^11.5
- rector/rector: ^2.0
- symfony/filesystem: ^7.4 || ^8.0
- symfony/framework-bundle: ^7.4 || ^8.0
- symfony/phpunit-bridge: ^7.4 || ^8.0
- symfony/security-bundle: ^7.4 || ^8.0
- symfony/yaml: ^7.4 || ^8.0
Suggests
- doctrine/doctrine-bundle: Required at runtime when nowo_api_token.enabled is true (tokens are stored through Doctrine DBAL)
- symfony/flex: For automatic recipe installation
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-19 04:43:50 UTC
README
⭐ Found this useful? Install it from Packagist and give it a star on GitHub: it helps us maintain and improve the project.
Personal API tokens for Symfony: hashed lookup tokens with per-module grants, a tenant reach, mandatory expiry, revocation, rate limits and audit events, one Bearer authenticator for every API and a UiKit account and operator UI.
Standard Symfony by default, DDD / hexagonal opt-in: zero configuration in a standard project; public ports are interfaces and value objects, bundle-owned tables are mapped in XML and referenced by id, the bundle never flushes your EntityManager.
🚧 Status: S1 core, first tag 0.1.0 pending its security audit. The package is built slice by slice from its design contract (docs/CONTRACT.md, 221-A). S1 ships the token store, format and hash, the issuer, revoker, query and authenticator services, the module registry and the
issue/purge-expiredcommands for standard and DDD hosts; the firewall, pages, bridges and HTTP API land with the next slices in docs/ROADMAP.md.
📋 Compatible with Symfony 7.4, 8.0 and 8.1 · PHP 8.2+ (Symfony 8.x requires PHP 8.4+)
This bundle is FrankenPHP worker mode friendly.
The demo shows the bundle registered, its container parameters and the MySQL connection.
Features
S1 (today) covers the token store, format, issuer, revoker, query and authenticator; the rest follows the roadmap.
-
FrankenPHP worker mode, kernel kept alive and not reset: no request state in services; a worker test (one kernel, 2,000 requests, two owners, revoke mid-run, flat memory) and the owner status read fresh on every request (docs/FRANKENPHP-WORKER-AUDIT.md).
-
Personal tokens issued to an owner (referenced by id): name, per-module grants (level + flags), a tenant reach, mandatory expiry (max 365 days), revoke, revoke all, erasure. Hash at rest (SHA-256), shown once, non-secret lookup id, CRC32 checksum for typo checks and secret scanning (
nwt_<lookup>_<secret><checksum>). -
One Bearer authenticator for Symfony firewalls (stateless), constant-time verification, owner status re-checked on every request, principal stamped on the request only.
-
Module registry: grants as data (
{tasks: read, mcp: on + destructive}), modules from config and bridges; a token only narrows the person's real permissions, never widens them. -
Security controls: one rate-limit bucket per token across every API, write sub-budget, failed tokens per IP, re-authentication before issue (password, or MFA through AuthKit), framing and
no-storeheaders, audit events after commit (ids only). -
UI on UiKit + FormKit: account page (list, New token dialog shown once, revoke, revoke all) and operator page.
-
Public API
GET/DELETE <prefix>/tokens/v1/selfwith OpenAPI; optional leak-report endpoint (off by default). -
Bridges (inside this bundle, active when installed): TaskBoard, Wiki, McpKit principals and rate limiters, HttpLog credential stamp, UserKit eraser / export / sessions listener, AuditKit, AuthKit re-auth.
Installation
composer require nowo-tech/api-token-bundle
See docs/INSTALLATION.md. Nothing is registered while nowo_api_token.enabled is false.
Requirements
- PHP >= 8.2, < 8.6 (Symfony 8.x needs PHP 8.4+)
- Symfony 7.4, 8.0 or 8.1
- Doctrine DBAL 4 (
doctrine/dbal^4.0) and ORM 3.3+ (doctrine/orm^3.3); DoctrineBundle once the bundle is enabled
Configuration
# config/packages/nowo_api_token.yaml nowo_api_token: enabled: false
Every key of the contract is already accepted (strict tree): docs/CONFIGURATION.md.
Demo
demo/symfony8: Symfony 8.1, FrankenPHP worker mode, MySQL, UiKit shell, Web Profiler, Twig Inspector and Hot Reload, on
http://localhost:8221 (make -C demo up). Playwright e2e: make -C demo/symfony8 test-e2e; refresh the screenshot above with
make -C demo/symfony8 demo-screenshots. See docs/DEMO-FRANKENPHP.md.
Documentation
- Installation
- Configuration
- Usage
- Contributing
- Code of Conduct
- Changelog
- Upgrading
- Release
- Security
- Engram
- Spec-driven development
- GitHub Spec Kit
- Roadmap
Additional documentation
- Contract 221-A
- Architecture
- FrankenPHP worker audit
- Concurrency
- Demo with FrankenPHP
- PSR compliance
- GitHub CI
Tests and coverage
make test # PHPUnit in Docker make test-coverage-100 # fails below 100 % of src/ make release-check # every gate, demo included
- PHP: 100 % of
src/(gate in CI).
License
MIT. See LICENSE.
Author
Created by Héctor Franco Aceituno at Nowo.tech.

