proxmox/docs/11-references/EXPLORER_ACCESS_API_REFERENCE.md

# Explorer Access API Reference

## Purpose

This is the quick-reference markdown companion to the explorer REST OpenAPI spec. It focuses on the access-management endpoints used by the `/access` console and RPC product layer.

Canonical machine-readable spec:

- `explorer-monorepo/backend/api/rest/swagger.yaml`

## Authentication types

### Wallet auth

Used for wallet-driven explorer tracks.

- `POST /api/v1/auth/nonce`
- `POST /api/v1/auth/wallet`

### User-session auth

Used for the explorer access console.

- `POST /api/v1/auth/register`
- `POST /api/v1/auth/login`
- `Authorization: Bearer <session-token>` for `/api/v1/access/*`

## Endpoints

### Register

`POST /api/v1/auth/register`

Request:

```json
{
  "email": "dev@example.com",
  "username": "devuser",
  "password": "strong-password"
}
```

Response:

```json
{
  "user": {
    "id": "uuid",
    "email": "dev@example.com",
    "username": "devuser",
    "is_admin": false
  },
  "token": "jwt",
  "expires_at": "2026-04-16T12:00:00Z"
}
```

### Login

`POST /api/v1/auth/login`

Request:

```json
{
  "email": "dev@example.com",
  "password": "strong-password"
}
```

### List products

`GET /api/v1/access/products`

Response shape:

```json
{
  "products": [
    {
      "slug": "thirdweb-rpc",
      "name": "Thirdweb RPC",
      "provider": "thirdweb",
      "vmid": 2103,
      "http_url": "http://192.168.11.217:8545",
      "ws_url": "ws://192.168.11.217:8546",
      "default_tier": "pro",
      "requires_approval": false,
      "billing_model": "subscription",
      "description": "Thirdweb-oriented Chain 138 RPC lane...",
      "use_cases": ["thirdweb integrations"],
      "management_features": ["API token issuance"]
    }
  ]
}
```

### Current user

`GET /api/v1/access/me`

Headers:

```http
Authorization: Bearer <session-token>
```

### List subscriptions

`GET /api/v1/access/subscriptions`

### Create or request subscription

`POST /api/v1/access/subscriptions`

Request:

```json
{
  "product_slug": "alltra-rpc",
  "tier": "pro"
}
```

Behavior:

- self-service products become `active`
- approval-gated products become `pending`

### List API keys

`GET /api/v1/access/api-keys`

### Create API key

`POST /api/v1/access/api-keys`

Request:

```json
{
  "name": "CI integration",
  "tier": "pro",
  "product_slug": "thirdweb-rpc",
  "expires_days": 30,
  "monthly_quota": 150000,
  "scopes": ["rpc:read", "rpc:write"]
}
```

Response:

```json
{
  "api_key": "ek_...",
  "record": {
    "id": "uuid",
    "name": "CI integration [thirdweb-rpc]",
    "tier": "pro",
    "productSlug": "thirdweb-rpc",
    "scopes": ["rpc:read", "rpc:write"],
    "monthlyQuota": 100000,
    "requestsUsed": 0,
    "approved": true,
    "rateLimitPerSecond": 20,
    "rateLimitPerMinute": 1000,
    "revoked": false,
    "createdAt": "2026-04-09T12:00:00Z"
  }
}
```

Important:

- plaintext API keys are only returned at creation time
- approval-gated products will reject creation until subscription is active
- `scopes` can be narrowed from the product defaults
- `expires_days: 0` or omission means no expiry

### Revoke API key

`POST /api/v1/access/api-keys/{id}`

Alternative:

`DELETE /api/v1/access/api-keys/{id}`

### Usage summary

`GET /api/v1/access/usage`

Response shape:

```json
{
  "usage": [
    {
      "product_slug": "thirdweb-rpc",
      "active_keys": 2,
      "requests_used": 1450,
      "monthly_quota": 200000
    }
  ]
}
```

### User audit feed

`GET /api/v1/access/audit?limit=20`

Returns recent validated API-key activity for the signed-in user.

### Admin audit feed

`GET /api/v1/access/admin/audit?limit=50&product=thirdweb-rpc`

Returns recent validated API-key activity across the platform for access admins. `product` is optional.

### Admin subscription review

`GET /api/v1/access/admin/subscriptions?status=pending`

Requires:

- `Authorization: Bearer <session-token>`
- the signed-in email must be listed in `ACCESS_ADMIN_EMAILS`

`POST /api/v1/access/admin/subscriptions`

Request:

```json
{
  "subscription_id": "uuid",
  "status": "active",
  "notes": "Approved for managed partner rollout"
}
```

Allowed `status` values:

- `active`
- `suspended`
- `revoked`

### Internal key validation

`POST /api/v1/access/internal/validate-key`

or

`GET /api/v1/access/internal/validate-key`

Headers:

```http
X-Access-Internal-Secret: <shared-secret>
```

Request:

```json
{
  "api_key": "ek_...",
  "method_name": "eth_call",
  "request_count": 1,
  "last_ip": "203.0.113.10"
}
```

Response:

```json
{
  "valid": true,
  "key": {
    "apiKeyId": "uuid",
    "userId": "uuid",
    "tier": "pro",
    "productSlug": "thirdweb-rpc",
    "scopes": ["rpc:read", "rpc:write"],
    "monthlyQuota": 100000,
    "requestsUsed": 1451,
    "rateLimitPerSecond": 20,
    "rateLimitPerMinute": 1000
  }
}
```

For nginx `auth_request`, use the `GET` form with headers instead of a JSON body:

```http
X-Access-Internal-Secret: <shared-secret>
X-API-Key: ek_...
X-Access-Method: eth_call
X-Access-Request-Count: 1
```

That flow returns `200` or `401` and may emit:

```http
X-Validated-Product: thirdweb-rpc
X-Validated-Tier: pro
X-Validated-Scopes: rpc:read,rpc:write
X-Quota-Remaining: 98549
```

## Error patterns

The REST API uses a consistent error shape:

```json
{
  "error": {
    "code": "bad_request",
    "message": "Unknown product"
  }
}
```

Common access-layer errors:

- `unauthorized`
- `bad_request`
- `subscription_required`
- `forbidden`
- `internal_error`

## Current caveats

- the access layer models subscriptions and quotas, but full edge enforcement is still separate work
- billing collection is not part of these endpoints yet
- admin approval workflow is exposed, but still driven by a simple email allowlist instead of a full RBAC system
- Thirdweb deployment orchestration is a separate backend/CI concern from these access endpoints

Related reference:

- [THIRDWEB_EXPLORER_PORTAL_DEPLOYMENT_MODEL.md](../04-configuration/THIRDWEB_EXPLORER_PORTAL_DEPLOYMENT_MODEL.md)