proxmox/docs/02-architecture/EXPLORER_ACCESS_CONTROL_AND_API_KEY_ARCHITECTURE.md

Explorer Access Control And API Key Architecture

Purpose

This document describes the explorer access-management plane added on top of the public Chain 138 explorer. It is the developer and operator reference for how user sessions, RPC products, subscriptions, and API keys are modeled today.

Scope

The access layer is for:

• commercial and managed access to RPC products
• user-facing account and API key management in the explorer
• future paywall and entitlement wiring for Thirdweb and Alltra lanes

It is not yet the final edge-enforcement layer for nginx, Besu, or relay proxies.

High-level model

There are now two auth systems in the explorer backend:

1. Wallet auth

Used for chain-oriented explorer tracks and wallet-based access.

Endpoints:

• POST /api/v1/auth/nonce
• POST /api/v1/auth/wallet

Token type:

• JWT signed with JWT_SECRET

Primary purpose:

• explorer track auth
• operator/track gating

2. User-session auth

Used for the /access console and API-key-management flows.

Endpoints:

• POST /api/v1/auth/register
• POST /api/v1/auth/login
• /api/v1/access/*

Token type:

• JWT signed with JWT_SECRET

Primary purpose:

• access-console identity
• subscriptions
• API key issuance and revocation
• usage summary

Backend components

REST layer

Relevant files:

• explorer-monorepo/backend/api/rest/auth.go
• explorer-monorepo/backend/api/rest/routes.go
• explorer-monorepo/backend/api/rest/server.go

Responsibilities:

• request validation
• user-session JWT issuance and validation
• mapping product catalog to API responses
• converting subscriptions into API-key eligibility

Auth/data layer

Relevant file:

• explorer-monorepo/backend/auth/auth.go

Responsibilities:

• user registration and password verification
• API key generation and hashing
• API key lookup and revocation
• product subscription persistence
• subscription and key listing

Database model

Migration:

• explorer-monorepo/backend/database/migrations/0015_access_management_schema.up.sql

Important tables:

rpc_products

Catalog of modeled RPC products.

Current seeds:

• core-rpc
• alltra-rpc
• thirdweb-rpc

user_product_subscriptions

Tracks per-user entitlement intent and state.

Important fields:

• product_slug
• tier
• status
• monthly_quota
• requests_used
• requires_approval
• approved_at
• approved_by
• notes

api_keys

Existing table extended with access-control metadata.

Important added fields:

• product_slug
• scopes
• monthly_quota
• requests_used
• approved
• approved_at
• approved_by
• last_ip_address

api_key_usage_logs

Reserved for live usage event ingestion and future billing/forensics work.

Product catalog semantics

core-rpc

• provider: besu-core
• VMID: 2101
• billing model: contract
• approval required: true

Intended for sensitive/operator-grade use. Subscription creation produces pending state until approved.

alltra-rpc

• provider: alltra
• VMID: 2102
• billing model: subscription
• approval required: false

Designed as self-service managed RPC access.

thirdweb-rpc

• provider: thirdweb
• VMID: 2103
• billing model: subscription
• approval required: false

Designed as self-service commercial API access for Thirdweb-aligned consumers.

API key lifecycle

Issuance

Flow:

1. user authenticates with email/password session
2. user requests or activates product subscription
3. user creates API key
4. backend assigns default scopes and quotas
5. plaintext key is returned once
6. only the hash is stored

Approval behavior

• self-service products create active subscriptions and approved keys
• approval-gated products create pending subscriptions and block key creation until activation

Revocation

Revocation is a soft state update:

• revoked = true

The current system does not yet implement key rotation workflow beyond revoke-and-recreate.

Frontend components

Relevant files:

• explorer-monorepo/frontend/src/pages/access/index.tsx
• explorer-monorepo/frontend/src/components/access/AccessManagementPage.tsx
• explorer-monorepo/frontend/src/services/api/access.ts

Responsibilities:

• register/login UX
• product catalog display
• subscription request/activation UX
• API key issuance and one-time secret display
• usage and quota summaries

Deliberate current gaps

These gaps are known and intentional, not accidental:

1. Edge enforcement is not yet fully wired.
2. Billing collection is not yet wired.
3. Admin approval UI does not yet exist.
4. Usage counters are not yet sourced from complete live edge metering.
5. Session and wallet identities are not yet linked into a single account model.

Recommended next implementation steps

1. Validate API keys at the RPC edge serving 2102 and 2103.
2. Add admin approval and suspension flows for core-rpc.
3. Feed live request events into api_key_usage_logs.
4. Add billing rail integration.
5. Add scoped permissions, rotation, and expiry controls to the access console.

Thirdweb-specific architecture boundary

For the thirdweb-rpc product, keep the architectural split explicit:

• the explorer portal owns identity, policy, approvals, and repo/deploy orchestration
• CI or a worker owns repository checkout and compilation
• the backend owns Thirdweb Engine/API secrets and deploy calls
• Blockscout owns verification truth for deployed contracts on Chain 138

The portal should not model Thirdweb Dashboard as if it were itself the system of record for private repository access or artifact generation.

See:

• THIRDWEB_EXPLORER_PORTAL_DEPLOYMENT_MODEL.md