Download the PHP package unquam/nette-api-auth without Composer

Nette API Auth

Nette API Auth is a straightforward API token authentication package for the Nette Framework. It was built because the Nette ecosystem lacked a solid, ready-to-use solution for token-based API authentication. Forking and adapting it to your own needs is very much welcome.

Requirements

PHP 7.4 or higher, Nette Framework 3.0, 3.1 or 3.2, and Nette Database 3.0, 3.1 or 3.2.

Installation

Database Setup

The package uses a separate api_users table to keep API authentication completely independent from your web authentication. Run the migration files in order - api_users must be created first because the other tables reference it.

Migrations are written for MySQL/MariaDB. If you use PostgreSQL or another database, use the table structure below as a reference and create migrations with your preferred tool.

The api_tokens table stores hashed access tokens. The refresh_tokens table stores hashed refresh tokens.

Configuration

First generate a secure secret key and keep it somewhere safe. This key is used to hash all tokens and must never change - if you change it, all existing tokens will become invalid.

Then register the extension in your config/common.neon and paste the generated key as the secret value.

The secret key is the only required field. Every other key has a sensible default and can be omitted if you are happy with the default value.

Token Lifetime Examples

Custom User Table Columns

If your api_users table uses different column names, map them with userColumns.

How Token Hashing Works

When a token is generated, the package creates a random raw value and stores only its HMAC-SHA256 hash in the database. The raw token is returned to you once and never stored again. On every subsequent request the incoming token is hashed with the same secret and compared against the stored hash, so even if someone reads your database they cannot recover usable tokens.

Rate Limiting

Rate limiting is applied automatically on every authenticated request. The package tracks how many requests each token has made within the current time window and compares that count against the configured limit. Test tokens and live tokens have separate limits.

Rate limit counters are stored using Nette\Caching\Storage. By default this uses the file cache that every Nette application already has — no extra infrastructure required. The cache cleans itself up automatically when entries expire, so there is no background job or cron needed.

When a request succeeds, the number of remaining requests in the current window is returned in the response header.

When the limit is exceeded the response is a 429 with a JSON error body.

Using Redis or Memcached for Rate Limiting

If you are running a high-traffic API and want rate limit counters stored in memory instead of on disk, register your preferred storage as a service and point the package to it with rateLimitStorage.

Any storage that implements Nette\Caching\Storage works — Redis, Memcached, APCu, or any custom driver.

Authentication Presenter

The first thing you need is an AuthPresenter that handles login and issues tokens. Extend it from BaseApiPresenter, mark the login action as public so it does not require a token, and inject the database to look up users.

Usage with BaseApiPresenter

Extend your API presenters from BaseApiPresenter and all authentication, rate limiting, and CORS handling is taken care of automatically on every request. Actions listed in the $publicActions property are skipped entirely, meaning no token is required to reach them.

Live and Test Mode

Every token is either a live token or a test token, determined by the third argument passed to generate().

Inside any action you can check which mode the current request is using and behave accordingly.

Scopes

Scopes let you attach fine-grained permissions to individual tokens. First declare the complete list of scopes your application supports in the configuration.

When generating a token, pass the scopes you want to assign as the fourth argument.

Inside a protected action you can then enforce scope requirements.

When a token was generated without any scopes, all scope checks pass automatically.

Refresh Tokens

When an access token expires the client can use a refresh token to get a new one without asking the user to log in again. Calling rotate() atomically revokes the old refresh token and generates a replacement in a single database transaction, preventing reuse even under concurrent requests. See the AuthPresenter example above for the full implementation.

Revoking Tokens

CORS

By default every origin is allowed. To restrict access to specific origins, set the corsOrigins list in the configuration.

When a request arrives from an origin that is not on the list, the response sets Access-Control-Allow-Origin: null, which causes browsers to block the response. A Vary: Origin header is always included so that caches and proxies handle origin-dependent responses correctly. Preflight OPTIONS requests are handled automatically and return HTTP 200 with the appropriate CORS headers before any authentication takes place.

Sending a Request

Pass the token in the Authorization header with every request that requires authentication.

In Postman, open the Auth tab on your request, select Bearer Token from the type dropdown, and paste the raw token value into the Token field. In Insomnia the same option is available under the Auth tab as Bearer.

Available Methods in BaseApiPresenter

getCurrentUser() returns an array with the keys user_id, email, role, is_live, token_id, expires_at, and scopes.

Usage with ApiAuthMiddleware

If your project uses contributte/middlewares you can use ApiAuthMiddleware instead of extending BaseApiPresenter. Install the optional dependency first.

The middleware is registered automatically by the DI extension. Configure public paths in your config/common.neon — any request whose path exactly matches or begins with one of those entries will pass through without a token.

When authentication succeeds the middleware attaches the user data to the request as an attribute named user, which subsequent middleware or handlers can read via $request->getAttribute('user'). The X-RateLimit-Remaining header is added to every successful response, and rate-limited requests receive a 429 with a JSON error body.

License

This package is open source. You are free to fork it, modify it and use it in your projects.