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](../04-configuration/THIRDWEB_EXPLORER_PORTAL_DEPLOYMENT_MODEL.md)