Scoped API tokens and presets for built-in integrations

Feature Requests
1

Reference Issues

Related but different: #239, #332

Those issues are about human admin roles / panel RBAC. This request is about machine/API credentials for integrations.

Summary

Remnawave currently has API tokens, but they appear to be all-or-nothing ROLE.API credentials. This creates unnecessary risk for common integrations that only need a small subset of API capabilities.

This is not only about custom private scripts. Existing Remnawave ecosystem tools already depend on API tokens:

  • remnawave/subscription-page requires REMNAWAVE_API_TOKEN, but at runtime it mainly needs metadata, subscription info, subscription page configs, and subscription responses.
  • Telegram commerce bots such as RWP Shop, Bedolaga Bot, and Remnashop use Remnawave API tokens for user/subscription/payment automation.
  • Telegram mini apps need narrow read access for subscription display.
  • MCP/AI integrations already implement client-side readonly mode, which is useful UX but not a backend security boundary.
  • Monitoring/DNS tools such as Cloudflare Nodes only need node/health read access.
  • Auto-installers create a subscription-page API token, but the current /api/tokens contract only accepts tokenName, so installers cannot create a least-privilege runtime token.

If one of these services is compromised, leaked, or misconfigured, the blast radius is much larger than the integration actually needs.

Basic Example

Add scopes/permissions to API tokens and expose built-in presets in the API token creation UI/API.

Example presets:

Subscription Page / Mini App

scopes:
  - metadata:read
  - users:read
  - subscriptions:read
  - subscription-pages:read
  - squads:read

Commerce bot

scopes:
  - users:read
  - users:write
  - users:actions
  - subscriptions:read
  - squads:read
  - hwid:read
  - bandwidth-stats:read

Drawbacks

  • Requires backend route/action authorization beyond the current ROLE.API check.
  • Requires database/model changes for API token scopes.
  • Needs careful naming/versioning of scopes so integrations do not break when routes evolve.
  • Some integrations need broad access, so a full-access token must probably remain available.
  • UI/API token creation becomes more complex, especially if custom scopes are supported in addition to presets.

Unresolved questions

  • Should scopes be resource/action based, route based, or both?
  • Should the first version start with built-in presets before custom scopes?
  • Should future versions support resource constraints, for example specific squads, nodes, or subscription page configs?
2

For extra context: I tried to explore this problem in an external proof of concept called RemnaGuard:

It is not intended as a proposal to merge this implementation into Remnawave. It is a separate Go gateway, so the code probably does not map directly to the current backend.

The parts that may be useful as prior art are the scope/policy model, route catalog idea, and a few integration-oriented policy examples such as subscription-page, readonly analytics, and user lifecycle bots.

I would be happy if any of this helps the discussion, even if the eventual Remnawave design is completely different.

P.S. Remnaguard was entirely vibecoded, so it may be sloppy code, it’s just a side-project, public alpha. Hope it still brings value.

3

Posted from: 💡 [REQUEST] - Scoped API tokens and presets for built-in integrations · Issue #433 · remnawave/panel · GitHub

4

Реализовано.

Функционал ожидается в релизе 2.8.0.

5

Neat! It’s awesome.

One more thing is, there is no way to edit current API tokens. There should be an option to edit current tokens permissions.