Sync workspace: config, docs, scripts, CI, operator rules, and submodule pointers.
- Update dbis_core, cross-chain-pmm-lps, explorer-monorepo, metamask-integration, pr-workspace/chains - Omit embedded publish git dirs and empty placeholders from index Made-with: Cursor
This commit is contained in:
defiQUG
339
docs/11-references/EXPLORER_ACCESS_API_REFERENCE.md
Normal file
339
docs/11-references/EXPLORER_ACCESS_API_REFERENCE.md
Normal file
@@ -0,0 +1,339 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user