phil / api-keys-bundle
Access tokens for a public Symfony API: hashed and shown once, scoped, expiring, revocable and rotated, checked by the access_token authenticator of Security.
Package info
github.com/parler-haut-interagir-librement/api-keys-bundle
Type:symfony-bundle
pkg:composer/phil/api-keys-bundle
Requires
- php: >=8.5
- ext-filter: *
- ext-mbstring: *
- ext-openssl: *
- ext-sodium: *
- doctrine/orm: ^3.7
- psr/clock: ^1.0
- psr/container: ^2.0
- psr/event-dispatcher: ^1.0
- symfony/config: ^8.2
- symfony/dependency-injection: ^8.2
- symfony/http-foundation: ^8.2
- symfony/http-kernel: ^8.2
- symfony/security-core: ^8.2
- symfony/security-http: ^8.2
- symfony/service-contracts: ^3.6
Requires (Dev)
- doctrine/dbal: ^4.5
- doctrine/doctrine-bundle: ^3.3
- phil/api-contract: ^0.1@dev
- phil/api-contract-bundle: ^0.3@dev
- phil/ip-anonymizer: ^0.1@dev
- phil/rate-limit-bundle: ^0.1@dev
- phil/url: ^0.1@dev
- phil/usage-meter-bundle: ^0.1@dev
- phpunit/phpunit: ^13.4
- psr/log: ^3.0
- symfony/browser-kit: ^8.2
- symfony/cache: ^8.2
- symfony/cache-contracts: ^3.6
- symfony/clock: ^8.2
- symfony/console: ^8.2
- symfony/css-selector: ^8.2
- symfony/dom-crawler: ^8.1
- symfony/event-dispatcher: ^8.2
- symfony/form: ^8.2
- symfony/framework-bundle: ^8.2
- symfony/http-client: ^8.2
- symfony/http-client-contracts: ^3.6
- symfony/options-resolver: ^8.2
- symfony/routing: ^8.2
- symfony/security-bundle: ^8.2
- symfony/security-csrf: ^8.2
- symfony/translation: ^8.2
- symfony/translation-contracts: ^3.6
- symfony/twig-bundle: ^8.2
- symfony/validator: ^8.2
- symfony/yaml: ^8.2
- twig/twig: ^3.21
Suggests
- phil/api-contract-bundle: To answer authentication failures with RFC 9457 problem details
- phil/ip-anonymizer: To keep an anonymized form of the address a token was last used from
- phil/rate-limit-bundle: For rate limits counted by token, with RateLimit headers
- phil/url: For the endpoint of GitHub's secret scanning, which checks the address of GitHub's keys
- phil/usage-meter-bundle: For quotas counted by token on meters, through phil/rate-limit-bundle
- symfony/cache: For the endpoint of GitHub's secret scanning, which keeps GitHub's keys in a cache pool
- symfony/console: For phil:api-keys:create, list, revoke and purge-expired
- symfony/form: For the page where members create and revoke their tokens
- symfony/http-client: For the endpoint of GitHub's secret scanning, which fetches GitHub's keys
- symfony/security-csrf: For the page where members create and revoke their tokens
- twig/twig: For the page where members create and revoke their tokens
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-21 03:09:02 UTC
README
Access tokens for a public API, for members, organisations or applications: shown once, kept as a keyed hash, scoped, expiring, revocable.
phil/api-keys-bundle lets the members of a Symfony application create tokens for its public API — a deploy script, a
spreadsheet, a home automation box — and lets the API know who calls and what for. A token acts for a member, or for
another owner type the configuration declares, such as an organisation or an application, loaded by its own user
provider and limited to the scopes that type may hold. A token reads
acme_3kTMd9qXbW1z_<32 characters><6 characters>: a prefix that names the application, so secret scanners recognise
it in a repository; an identifier that finds its row; a secret drawn from the secure source of random_bytes(); and a
CRC-32 checksum that refuses a mistyped or truncated token offline, before any lookup. The text is shown once, at
creation; the table keeps only the HMAC-SHA-256 of the secret under a key from the secrets vault, compared in constant
time, written with the name of its algorithm and version. The keys are an ordered list: the first hashes, every one
verifies, so the key rotates without cutting the tokens issued under the previous one.
Every token holds scopes the configuration declares, with a description for developers and a translatable label for
members, and every token expires, within a longest lifetime the configuration sets. A token is revoked at once — one,
or every token of an owner —, or rotated: a successor with the same scopes, the old token revoked or kept for a grace
period while the client switches. Its last use is written at most once per interval, with the client's address only as
phil/ip-anonymizer anonymizes it.
A stateless firewall gives Symfony's access_token authenticator the bundle's token handler: Authorization: Bearer <token> or another header, the user loaded by the token's owner through the provider of its type, the scopes as roles
and attributes, a voter and
#[RequiresScope('projects:write')] on controllers. A refused token is answered 401 with the challenge of RFC 6750
— as RFC 9457 problem details when phil/api-contract-bundle is installed —, a missing scope 403 insufficient_scope.
Rate limits and quotas count per token through phil/rate-limit-bundle and phil/usage-meter-bundle, with their
RateLimit headers. Commands create, list, revoke and purge tokens, and an optional page lets members manage theirs,
and those of an organisation or an application when the application's voters allow them. An optional endpoint receives
the tokens GitHub's secret scanning finds in public repositories, verifies GitHub's signature and revokes them. The
events carry identifiers only, for an audit trail.
It is a bundle built on Symfony Security, Doctrine ORM and PSR-20; the console, the form component, Twig,
phil/api-contract-bundle, phil/rate-limit-bundle, phil/ip-anonymizer, and Symfony's HTTP client and cache for
the secret scanning endpoint, are optional. Its services keep no state between requests and serve a long-running
worker; the store in memory is emptied between requests.
The design follows the layers of the monorepo: Domain holds the token format, the owner, the row ApiToken, the
port of the store and the events; Application holds ApiTokens, the hasher, the scope catalogue, the owner types and
the port of the address anonymizer; Infrastructure holds the Doctrine and in-memory stores, the token handler and the listener of the roles,
the voter and the attribute, the endpoint of GitHub's secret scanning, the integrations, the commands, the form and the
page, and the service wiring.
Status
| Part | State |
|---|---|
| Token format with prefix, identifier, secret and checksum; strict reader, fuzzed | Implemented and tested |
| Keyed hash only, naming its algorithm and version, compared in constant time; text shown once; ordered keys for rotation | Implemented and tested |
| Typed owners — members, organisations, applications — loaded by their own user providers, scopes per type, revocation of every token of an owner | Implemented and tested |
| Scopes declared in configuration, descriptions and translatable labels | Implemented and tested |
| Required expiry within a longest lifetime; revocation; rotation with grace; purge | Implemented and tested |
| Last use written once per interval, address anonymized or not kept | Implemented and tested |
Token handler for Symfony's access_token authenticator, scope roles and attributes, voter, #[RequiresScope], RFC 6750 challenges |
Implemented and tested |
| Endpoint of GitHub's secret scanning: signature verified, leaked tokens revoked; disabled by default | Implemented and tested |
Problem details with phil/api-contract-bundle, rate limits by token with phil/rate-limit-bundle |
Implemented and tested |
| Commands; members' page and the page of another owner's tokens behind a voter, in English and French | Implemented and tested |
| Doctrine store and store in memory, emptied between requests | Implemented and tested |
Documentation
| Document | What it covers |
|---|---|
| Installation | Requirements, registering the bundle, the key, the table, the firewall. |
| Configuration | Every option of phil_api_keys. |
| Tokens | The format, what is stored, creating, rotating, revoking, purging, the last use. |
| Authentication and scopes | The firewall, the roles and attributes, the voter, #[RequiresScope], the answers. |
| Secret scanning | The endpoint GitHub posts leaked tokens to: enabling it, the signature, the revocation, the keys. |
| The members' page | The routes, the form, the templates, the translations. |
| Integrations | Quotas, problem details, anonymized addresses, the events for an audit trail. |
| Console | The four commands. |
| Exceptions | What the bundle throws, and when. |
| Extension points | What an application implements, configures, replaces or relies on. |
| Testing | The bundle's tests, fuzz targets and benchmark, and how to test an application that uses it. |
| Reference | Every type of the bundle, with its role. |
Quick start
composer require phil/api-keys-bundle
bin/console secrets:set API_KEYS_HASH_KEY # 32 random bytes or more
# config/packages/phil_api_keys.yaml phil_api_keys: prefix: acme hash_key: '%env(API_KEYS_HASH_KEY)%' scopes: projects:read: { description: 'Read the projects', label: 'scope.projects_read' } projects:write: { description: 'Create and change projects', label: 'scope.projects_write' } # config/packages/security.yaml security: firewalls: api: pattern: ^/api/ stateless: true access_token: token_handler: phil_api_keys.token_handler token_extractors: [phil_api_keys.token_extractor] realm: api
#[RequiresScope('projects:read')] final class ProjectController { #[RequiresScope('projects:write')] public function update(): Response { // ... } }
curl -H "Authorization: Bearer acme_3kTMd9qXbW1z_…" https://example.com/api/projects
Requirements
PHP 8.5 or later, Symfony 8.2 with its Security components, Doctrine ORM 3.7.
Contributing
Contributions are welcome on the PHIL monorepo: read the contribution guide and the code of conduct. Report a vulnerability privately, as the security policy explains, never in a public issue.
License
MIT, © Philippe Gamache, doing business as Le Gnome Archiviste; a Parler Haut Interagir Librement project. See LICENSE.