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:

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

Response:

{
  "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:

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

List products

GET /api/v1/access/products

Response shape:

{
  "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:

Authorization: Bearer <session-token>

List subscriptions

GET /api/v1/access/subscriptions

Create or request subscription

POST /api/v1/access/subscriptions

Request:

{
  "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:

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

Response:

{
  "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:

{
  "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:

{
  "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:

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

Request:

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

Response:

{
  "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:

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:

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:

{
  "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