Download the PHP package bombenprodukt/laravel-zeus without Composer

About Laravel Zeus

This project was created by, and is maintained by Brian Faust, and is a Laravel-compatible API token manager featuring prefix and ability scoping support. Be sure to browse through the security policy.

Design

Laravel Zeus, in terms of design goals, is akin to Laravel Sanctum. It offers a lightweight authentication system for APIs, similar to Sanctum. However, it's important to note that Zeus isn't meant to replace Sanctum, Passport, or Fortify. Instead, it serves as a simpler alternative for developers who don't need the extensive features of the aforementioned systems. Its primary function is to authenticate users using easily identifiable API tokens. This design choice makes it simpler to detect and revoke tokens.

All the access tokens are stored in the access_tokens table and are prefixed at the time of generation. The prefixing helps distinguish the token types, for instance, pat is used for personal access tokens. We employ TypeID to generate these tokens. It creates type-safe, K-sortable, and globally unique API keys. The design is inspired by the system used by Stripe IDs.

Moreover, Laravel Zeus offers the option to restrict tokens to particular abilities and domains. This measure adds another layer of control over their usage. Tokens can also be programmed to expire after a specified duration from their creation. This feature is especially useful for creating short-lived tokens for one-time-use scenarios or long-lived tokens for trusted applications. This auto-expiry function not only enhances security but also enforces regular token rotation, mitigating the risks associated with a permanent token leak.

Installation

Note This package requires PHP 8.2 or later, and it supports Laravel 10 or later.

To get the latest version, simply require the project using Composer:

You can publish the migrations by using:

You can publish the configuration file by using:

Usage

Note Please review the contents of our test suite for detailed usage examples.

The first step to get started is to prepare your model by implementing the HasAccessTokensInterface interface. This can be done by including the HasAccessTokens trait, which provides default implementations for all necessary methods. The process is as follows:

Once you've completed that, you can open your routes/api.php file and replace auth:sanctum with auth:zeus. Everything should work as before, provided you use valid Zeus access tokens.

Now that you've set up your model, you could create a controller to store an access token based on user input, such as providing a name for it. Take a look at the PendingAccessToken class for all available getters and setters. However, in most cases, it's enough to stick to the defaults once you've configured them to match your use case.

If you want to apply rate limiting per access token rather than user ID or IP address, you could achieve this by modifying the API Rate Limiter inside the app/Providers/RouteServiceProvider.php file and specifying the access token as the identifier for rate limiting attempts.