[Discussion] Support for Scoped API Tokens / Permission-Bound API Keys

[HashGateApp]

Background

Right now, API tokens are typically “all or nothing,” inheriting the full access of the underlying user. Adding scoped API tokens would allow tokens to be restricted to specific actions or resources, improving security for programmatic access and external integrations.

This thread aims to clarify:

• how scopes should be represented,
• how they interact with team-based permissions,
• and how they should be stored and enforced.

User Stories

• As a developer, I want to issue API tokens with specific scopes so my users can programmatically access only the parts of the API they need.
• As an end user, I want to generate API tokens that are limited in capability and safe to expose to third-party integrations.
• As an administrator, I want visibility into scopes, what they represent, and which tokens have which scopes.
• As the system, I want a consistent way to enforce scopes at the middleware/policy/gate level, regardless of whether the actor is a user or a token.

Open Questions

1. How should we handle scenarios where a model that extends the Illuminate\Foundation\Auth\User type and is used as the authenticated source?

In some flows, the authenticated actor extends the Illuminate\Foundation\Auth\User model rather than the default App\Models\User model. This raises questions:

• Should scope/permission evaluation always be normalized to the underlying Illuminate\Foundation\Auth\User model before evaluating team permissions?
• Should scoped tokens be allowed to act as their own “team actor” (e.g., token -> team relationship) independent of a user?
• How does this impact the evaluation chain in policies like:
  token scopes -> team membership -> team permissions -> resource ownership?

2. Where should scoped permissions be stored?

There are two main patterns to consider:

Option A: Store scopes directly on the issued token

Example: a JSON column on the token such as:

["teams.view", "teams.users.view", "charges.create"]

Option B: — Treat the token as a permissioned entity within the team

This approach creates a team association for the token model (e.g., TeamToken, HasTeam-like trait) and grants it permissions using the same mechanism used for users.

Things to consider

• Should scopes be stored directly on the token, or modeled using the existing team permission system?
• Do we need a unified Actor interface that both Users and Tokens implement?

[Jurager]

@HashGateApp

This is an interesting question, but it's worth clarifying right away whether we're trying to delegate responsibility for token creation to the package or whether we're using a third-party solution and should allow users to integrate with it—for example, with Sanctum.

Here's an example of how it's currently done in our projects: we can create an unlimited number of tokens assigned to a user and set an expiration time for them. All tokens essentially identify a specific user, and then we check all their roles/rights, etc., using this package. So, in short, we don't use scoped tokens at all.

Now regarding the question:

What I see as illogical is using tokens as a separate team subject, since a token is simply a user identification in the system.

As for the token scope in this situation, it's worth considering the following: if a user already has certain permissions defined by the package, should the token scope provide a choice of available ones? Because in all other cases, this violates the rights verification chain.

So now I see this option: if we want to use tokens with limited scope, then their scopes should be inherited from the package permissions for this user (maybe with the ability to revoke a specific token scope?)

And here we come back to the question of where we'll delegate token creation, as this will determine where and how we'll store them. In the design of this package, we wanted to maintain maximum flexibility, so imposing a framework on users isn't quite the right solution. There are a ton of solutions people use for working with tokens — it seems our goal is to provide them with some kind of adapter that will allow them to easily configure integration with the package.

[HashGateApp]

I've been reflecting on your comment, and I agree that we should aim for operability with the existing tools (Sanctum, Passport, and JWTs).

I think that the solution of providing an adapter that models can use to provide permissions would result in the best outcome for this package