{ "components": { "schemas": { "big.Int": { "type": "object" }, "data": { "properties": { "data": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_explorer.AddressStats" }, "type": "array" } }, "type": "object" }, "iden3comm.AttachData": { "properties": { "json": {} }, "type": "object" }, "iden3comm.Attachment": { "properties": { "data": { "$ref": "#/components/schemas/iden3comm.AttachData" }, "description": { "type": "string" }, "format": { "type": "string" }, "id": { "type": "string" }, "media_type": { "type": "string" } }, "type": "object" }, "internal_server.APIError": { "properties": { "error": { "example": "invalid request", "type": "string" } }, "type": "object" }, "internal_server.APIMessage": { "properties": { "message": { "example": "operation completed", "type": "string" } }, "type": "object" }, "internal_server.AddressTransactionsResponse": { "properties": { "next_cursor": { "type": "string" }, "transactions": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_explorer.Transaction" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_server.AddressTransfersResponse": { "properties": { "next_cursor": { "type": "string" }, "transfers": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_explorer.TokenTransfer" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_server.AdminLogsResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_db.AccessLog" }, "type": "array", "uniqueItems": false }, "limit": { "example": 100, "type": "integer" }, "offset": { "example": 0, "type": "integer" }, "total": { "example": 1, "type": "integer" } }, "type": "object" }, "internal_server.ApproveDisclosureRequestBody": { "properties": { "grant_duration_hours": { "example": 24, "type": "integer" }, "reason": { "example": "approved for audit window", "type": "string" }, "scope": { "$ref": "#/components/schemas/privacy-proxy_internal_disclosure.Scope" } }, "type": "object" }, "internal_server.AuditLogEntryDoc": { "properties": { "action": { "description": "create, update, delete, assign, revoke", "type": "string" }, "actor_external_id": { "type": "string" }, "actor_id": { "type": "string" }, "created_at": { "type": "string" }, "id": { "type": "integer" }, "ip_address": { "type": "string" }, "new_value": { "additionalProperties": {}, "type": "object" }, "old_value": { "additionalProperties": {}, "type": "object" }, "org_id": { "description": "parent org of the affected resource (audit H1 — used for cross-org scoping of the list endpoint)", "type": "string" }, "resource_id": { "type": "string" }, "resource_name": { "type": "string" }, "resource_type": { "type": "string" } }, "type": "object" }, "internal_server.AuthRequestBody": { "properties": { "callback_origin": { "description": "CallbackOrigin is the browser's window.location.origin (e.g., \"http://max-mac:5173\")\nUsed to construct callback URLs that work from any hostname (localhost, Tailscale, etc.)", "type": "string" } }, "type": "object" }, "internal_server.AuthRequestResponse": { "properties": { "auth_request": { "$ref": "#/components/schemas/protocol.AuthorizationRequestMessage" }, "session_id": { "type": "string" } }, "type": "object" }, "internal_server.AuthResponse": { "properties": { "access_token": { "type": "string" }, "expires_in": { "description": "seconds", "type": "integer" }, "refresh_token": { "type": "string" }, "token_type": { "type": "string" } }, "type": "object" }, "internal_server.AuthVerifyRequest": { "properties": { "jwz_token": { "type": "string" }, "session_id": { "type": "string" } }, "required": [ "jwz_token", "session_id" ], "type": "object" }, "internal_server.AzureCallbackRequest": { "properties": { "code": { "type": "string" }, "redirect_uri": { "type": "string" }, "state": { "type": "string" } }, "required": [ "code", "redirect_uri", "state" ], "type": "object" }, "internal_server.AzureServicePrincipalRequest": { "properties": { "access_token": { "type": "string" } }, "required": [ "access_token" ], "type": "object" }, "internal_server.AzureURLResponse": { "properties": { "state": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "internal_server.ChallengeResponse": { "properties": { "message": { "type": "string" }, "nonce": { "type": "string" } }, "type": "object" }, "internal_server.ComplianceAffectedToken": { "properties": { "org_id": { "type": "string" }, "symbol": { "example": "ETH", "type": "string" }, "token_address": { "example": "native", "type": "string" } }, "type": "object" }, "internal_server.ComplianceBaseCurrencyResponse": { "properties": { "all_currencies": { "items": { "$ref": "#/components/schemas/internal_server.ComplianceCurrencyInfo" }, "type": "array", "uniqueItems": false }, "coingecko_enabled": { "example": true, "type": "boolean" }, "currency": { "example": "usd", "type": "string" } }, "type": "object" }, "internal_server.ComplianceConfigUpdateRequest": { "properties": { "currency": { "example": "usd", "type": "string" }, "enabled": { "example": true, "type": "boolean" }, "enforcement_mode": { "example": "enforce", "type": "string" }, "threshold_fiat": { "example": 1000, "type": "number" }, "unknown_price_policy": { "example": "forbidden", "type": "string" } }, "type": "object" }, "internal_server.ComplianceCurrencyConflictResponse": { "properties": { "affected_tokens": { "items": { "$ref": "#/components/schemas/internal_server.ComplianceAffectedToken" }, "type": "array", "uniqueItems": false }, "currency": { "example": "eur", "type": "string" }, "error": { "example": "manual token prices are missing for the target currency; set force=true to switch anyway", "type": "string" } }, "type": "object" }, "internal_server.ComplianceCurrencyInfo": { "properties": { "code": { "example": "usd", "type": "string" }, "name": { "example": "US Dollar", "type": "string" }, "symbol": { "example": "$", "type": "string" } }, "type": "object" }, "internal_server.ComplianceDataResponse": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": { "items": {}, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_server.ComplianceListResponse": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": { "items": {}, "type": "array", "uniqueItems": false }, "limit": { "example": 50, "type": "integer" }, "offset": { "example": 0, "type": "integer" }, "total": { "example": 42, "type": "integer" } }, "type": "object" }, "internal_server.ComplianceSanctionAddRequest": { "properties": { "address": { "example": "0x0000000000000000000000000000000000000001", "type": "string" }, "org_id": { "type": "string" }, "reason": { "example": "OFAC SDN listing", "type": "string" }, "source": { "example": "manual", "type": "string" } }, "required": [ "address", "reason" ], "type": "object" }, "internal_server.ComplianceSetBaseCurrencyRequest": { "properties": { "currency": { "example": "eur", "type": "string" }, "force": { "example": false, "type": "boolean" } }, "required": [ "currency" ], "type": "object" }, "internal_server.ComplianceSetBaseCurrencyResponse": { "properties": { "affected_tokens": { "items": { "$ref": "#/components/schemas/internal_server.ComplianceAffectedToken" }, "type": "array", "uniqueItems": false }, "currency": { "example": "eur", "type": "string" }, "message": { "example": "Base currency updated to EUR.", "type": "string" }, "warning": { "type": "string" } }, "type": "object" }, "internal_server.ComplianceSystemTokenPrice": { "properties": { "coingecko_id": { "example": "ethereum", "type": "string" }, "decimals": { "example": 18, "type": "integer" }, "id": { "example": 1, "type": "integer" }, "is_stale": { "example": false, "type": "boolean" }, "price_fiat": { "example": 3500, "type": "number" }, "source": { "example": "coingecko", "type": "string" }, "symbol": { "example": "ETH", "type": "string" }, "token_address": { "type": "string" }, "updated_at": { "example": "2026-01-02T15:04:05Z", "type": "string" } }, "type": "object" }, "internal_server.ComplianceSystemTokenPriceListResponse": { "properties": { "currency": { "example": "usd", "type": "string" }, "data": { "items": { "$ref": "#/components/schemas/internal_server.ComplianceSystemTokenPrice" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_server.ComplianceThresholdOverrideUpsertRequest": { "properties": { "note": { "example": "elevated limit for treasury address", "type": "string" }, "threshold_fiat": { "example": 5000, "type": "number" } }, "type": "object" }, "internal_server.ComplianceTokenPriceUpsertRequest": { "properties": { "coingecko_id": { "example": "ethereum", "type": "string" }, "decimals": { "example": 18, "type": "integer" }, "prices": { "additionalProperties": { "type": "number" }, "type": "object" }, "symbol": { "example": "ETH", "type": "string" } }, "required": [ "symbol" ], "type": "object" }, "internal_server.ComplianceTravelRuleRecordCreateRequest": { "properties": { "amount_wei": { "example": "1000000000000000000", "type": "string" }, "beneficiary_address": { "example": "0x0000000000000000000000000000000000000001", "type": "string" }, "beneficiary_data": { "additionalProperties": {}, "type": "object" }, "originator_data": { "additionalProperties": {}, "type": "object" }, "originator_user_id": { "type": "string" }, "token_address": { "type": "string" }, "transfer_type": { "example": "eth", "type": "string" } }, "required": [ "amount_wei", "beneficiary_address", "beneficiary_data", "originator_data", "originator_user_id", "transfer_type" ], "type": "object" }, "internal_server.ContractSyncStatus": { "properties": { "address": { "type": "string" }, "error": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "status": { "description": "\"exists\", \"missing\", \"error\"", "type": "string" } }, "type": "object" }, "internal_server.CreateDisclosureRequestBody": { "properties": { "expires_in_hours": { "example": 72, "type": "integer" }, "legal_basis": { "example": "GDPR Art. 6(1)(c)", "type": "string" }, "org_id": { "example": "00000000-0000-0000-0000-000000000001", "type": "string" }, "reason": { "example": "regulatory audit", "type": "string" }, "requester_did": { "example": "did:example:auditor", "type": "string" }, "requester_user_id": { "example": "user-123", "type": "string" }, "scope": { "$ref": "#/components/schemas/privacy-proxy_internal_disclosure.Scope" }, "target_user_id": { "example": "user-456", "type": "string" } }, "type": "object" }, "internal_server.DeployDemoERC20Request": { "properties": { "name": { "description": "optional - contract name, defaults to \"DemoERC20\"", "type": "string" }, "org_id": { "description": "optional - auto-register to this org", "type": "string" } }, "type": "object" }, "internal_server.DeployDemoERC20Response": { "properties": { "address": { "type": "string" }, "name": { "type": "string" }, "registered": { "type": "boolean" }, "tx_hash": { "type": "string" } }, "type": "object" }, "internal_server.DisclosedAddress": { "properties": { "address": { "description": "Pseudonym for pseudonymous, \"[PRIVATE]\" for redacted, real for full", "type": "string" }, "address_id": { "description": "Opaque identifier for routing (hash of real address)", "type": "string" }, "disclosure_level": { "type": "string" }, "ens_name": { "description": "Only included for full disclosure", "type": "string" }, "expires_at": { "type": "string" }, "grant_id": { "type": "string" }, "owner_did": { "type": "string" } }, "type": "object" }, "internal_server.DisclosureApproveResponse": { "properties": { "grant": { "$ref": "#/components/schemas/privacy-proxy_internal_disclosure.Grant" }, "message": { "example": "Access granted. Authorized viewer can access data via their authenticated session.", "type": "string" } }, "type": "object" }, "internal_server.DisclosureCheckAccessResponse": { "properties": { "disclosure_level": { "$ref": "#/components/schemas/privacy-proxy_internal_disclosure.DisclosureLevel" }, "expires_at": { "example": "2026-01-01T00:00:00Z", "type": "string" }, "grant_id": { "example": "11111111-1111-1111-1111-111111111111", "type": "string" }, "has_access": { "example": true, "type": "boolean" }, "message": { "example": "No active disclosure grant found", "type": "string" }, "scope": { "$ref": "#/components/schemas/privacy-proxy_internal_disclosure.Scope" } }, "type": "object" }, "internal_server.DisclosureReasonBody": { "properties": { "reason": { "example": "no longer required", "type": "string" } }, "type": "object" }, "internal_server.DisclosureStatusResponse": { "properties": { "status": { "enum": [ "deleted", "revoked", "rejected" ], "type": "string" } }, "type": "object" }, "internal_server.EthAddressListResponse": { "properties": { "addresses": { "items": { "$ref": "#/components/schemas/internal_server.EthAddressResponse" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_server.EthAddressResponse": { "properties": { "address": { "type": "string" }, "ens_name": { "type": "string" }, "ens_resolved_at": { "type": "string" }, "verified_at": { "type": "string" } }, "type": "object" }, "internal_server.EthLinkENSResponse": { "properties": { "address": { "example": "0x70997970c51812dc3a010c7d01b50e0d17dc79c8", "type": "string" }, "ens_name": { "example": "alice.eth", "type": "string" } }, "type": "object" }, "internal_server.EthLinkVerifyResponse": { "properties": { "address": { "example": "0x70997970c51812dc3a010c7d01b50e0d17dc79c8", "type": "string" }, "message": { "example": "address linked successfully", "type": "string" } }, "type": "object" }, "internal_server.ExplorerABIUpdateResponse": { "properties": { "address": { "example": "0x0000000000000000000000000000000000000001", "type": "string" }, "success": { "example": true, "type": "boolean" } }, "type": "object" }, "internal_server.ExplorerBlockNumberResponse": { "properties": { "number": { "example": 1234567, "type": "integer" } }, "type": "object" }, "internal_server.ExplorerCatchupProgressResponse": { "properties": { "isRunning": { "example": false, "type": "boolean" }, "percentComplete": { "example": 0, "type": "integer" }, "processed": { "example": 0, "type": "integer" }, "total": { "example": 0, "type": "integer" } }, "type": "object" }, "internal_server.ExplorerChainIDResponse": { "properties": { "chain_id": { "example": 1, "type": "integer" } }, "type": "object" }, "internal_server.ExplorerIsContractResponse": { "properties": { "is_contract": { "example": true, "type": "boolean" } }, "type": "object" }, "internal_server.ExplorerListResponse": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": { "items": {}, "type": "array", "uniqueItems": false }, "total": { "example": 25, "type": "integer" } }, "type": "object" }, "internal_server.ExtraWildcardInfo": { "properties": { "deny": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "prefix": { "type": "string" } }, "type": "object" }, "internal_server.GrantActivityLogEntry": { "properties": { "method": { "type": "string" }, "status_code": { "type": "integer" }, "timestamp": { "description": "RFC 3339", "type": "string" } }, "type": "object" }, "internal_server.GrantActivityLogsResponse": { "properties": { "limit": { "type": "integer" }, "logs": { "items": { "$ref": "#/components/schemas/internal_server.GrantActivityLogEntry" }, "type": "array", "uniqueItems": false }, "offset": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" }, "internal_server.GrantTransaction": { "properties": { "block_number": { "type": "integer" }, "block_timestamp": { "type": "integer" }, "direction": { "description": "\"in\", \"out\", \"self\"", "type": "string" }, "from": { "type": "string" }, "gas_used": { "type": "integer" }, "status": { "type": "integer" }, "to": { "type": "string" }, "tx_hash": { "description": "only for full disclosure", "type": "string" }, "value": { "type": "string" } }, "type": "object" }, "internal_server.GrantTransactionsResponse": { "properties": { "address_labels": { "additionalProperties": { "type": "string" }, "type": "object" }, "disclosure_level": { "type": "string" }, "next_cursor": { "description": "NextCursor is the opaque continuation to pass back as ?cursor= (RD-1149).\nIts presence is the sole \"more pages\" signal: a client keeps paging while\nnext_cursor is present and stops when it is omitted (feed exhausted). It is\ndeliberately the only pagination field — there is no has_more, which would\nonly ever be `next_cursor != \"\"` and could drift from it.", "type": "string" }, "transactions": { "items": { "$ref": "#/components/schemas/internal_server.GrantTransaction" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_server.HumanityVerificationError": { "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "verify_url": { "type": "string" } }, "type": "object" }, "internal_server.IntrospectResponse": { "properties": { "active": { "type": "boolean" }, "exp": { "description": "Expiration time", "type": "integer" }, "iat": { "description": "Issued at time", "type": "integer" }, "kyc": { "description": "KYC status (only for access tokens)", "type": "boolean" }, "sub": { "description": "Subject (user DID)", "type": "string" }, "token_type": { "description": "\"access_token\" or \"refresh_token\"", "type": "string" } }, "type": "object" }, "internal_server.JSONRPCError": { "description": "Error is set on a JSON-RPC-level failure; omitted on success.", "properties": { "code": { "example": -32601, "type": "integer" }, "message": { "example": "method not found", "type": "string" } }, "type": "object" }, "internal_server.JSONRPCRequestEnvelope": { "properties": { "id": { "description": "ID is the client-chosen request id echoed back on the response. May be a\nstring, a number, or null per the JSON-RPC spec.", "example": 1, "type": "integer" }, "jsonrpc": { "description": "JSONRPC is the protocol version; always \"2.0\".", "example": "2.0", "type": "string" }, "method": { "description": "Method is the JSON-RPC method name (e.g. eth_blockNumber, eth_call,\neth_sendTransaction). Anonymous callers are limited to the anonymous\nmethod allowlist.", "example": "eth_blockNumber", "type": "string" }, "params": { "description": "Params are the positional method parameters. Shape is method-specific.", "items": {}, "type": "array", "uniqueItems": false }, "privateFor": { "description": "PrivateFor is an accepted alias for VisibleTo (union of both is applied).", "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "visibleTo": { "description": "VisibleTo is the optional RD-1163 per-transaction visibility list (DIDs\nand/or linked ETH addresses). Only meaningful for log-emitting contract\nsends. Alias: privateFor.", "example": [ "did:example:alice", "0x0000000000000000000000000000000000000001" ], "items": { "type": "string" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_server.JSONRPCResponseEnvelope": { "properties": { "error": { "$ref": "#/components/schemas/internal_server.JSONRPCError" }, "id": { "description": "ID echoes the request id.", "example": 1, "type": "integer" }, "jsonrpc": { "description": "JSONRPC is the protocol version; always \"2.0\".", "example": "2.0", "type": "string" }, "result": { "description": "Result is the method result on success. Shape is method-specific;\nomitted when error is set." } }, "type": "object" }, "internal_server.MethodsStatus": { "properties": { "extra_namespaces": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "type": "object" }, "extra_wildcards": { "additionalProperties": { "$ref": "#/components/schemas/internal_server.ExtraWildcardInfo" }, "type": "object" } }, "type": "object" }, "internal_server.MyAdminStatusResponse": { "properties": { "admin_org_ids": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "is_admin": { "example": true, "type": "boolean" }, "is_readonly_admin": { "example": false, "type": "boolean" }, "readonly_admin_org_ids": { "items": { "type": "string" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_server.MyOrganizationsResponse": { "properties": { "organizations": { "items": { "$ref": "#/components/schemas/internal_server.UserOrgResponse" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_server.NodeStatus": { "properties": { "error": { "type": "string" }, "latency_ms": { "type": "integer" }, "status": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "internal_server.OAuthErrorResponse": { "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "type": "object" }, "internal_server.OAuthSessionStatusResponse": { "properties": { "completed": { "type": "boolean" }, "redirect_url": { "type": "string" } }, "type": "object" }, "internal_server.OAuthTokenRequest": { "properties": { "client_id": { "form": "client_id", "type": "string" }, "client_secret": { "description": "RD-1006 client_secret_post; client_secret_basic also accepted via HTTP Basic", "form": "client_secret", "type": "string" }, "code": { "form": "code", "type": "string" }, "grant_type": { "form": "grant_type", "type": "string" }, "redirect_uri": { "form": "redirect_uri", "type": "string" } }, "required": [ "client_id", "code", "grant_type", "redirect_uri" ], "type": "object" }, "internal_server.OAuthTokenResponse": { "properties": { "access_token": { "type": "string" }, "expires_in": { "type": "integer" }, "refresh_token": { "type": "string" }, "token_type": { "type": "string" } }, "type": "object" }, "internal_server.OwnAddress": { "properties": { "address": { "type": "string" }, "ens_name": { "type": "string" } }, "type": "object" }, "internal_server.ProvidersResponse": { "properties": { "providers": { "items": { "type": "string" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_server.ProxyStatus": { "properties": { "port": { "type": "string" }, "status": { "type": "string" } }, "type": "object" }, "internal_server.RefreshRequest": { "properties": { "refresh_token": { "type": "string" } }, "required": [ "refresh_token" ], "type": "object" }, "internal_server.ResolveAddressResponse": { "properties": { "disclosure_level": { "type": "string" }, "grant_id": { "type": "string" }, "pseudonym": { "description": "For pseudonymous, the display name to use", "type": "string" }, "real_address": { "type": "string" }, "scope_methods": { "description": "Methods from grant scope (e.g. \"transaction_history\", \"activity_logs\")", "items": { "type": "string" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_server.RevokeRequest": { "properties": { "access_token": { "description": "Optional: if provided, also revokes the access token", "type": "string" }, "refresh_token": { "type": "string" } }, "required": [ "refresh_token" ], "type": "object" }, "internal_server.SecurityStatus": { "properties": { "compliance_default_mode": { "description": "ComplianceDefaultMode is the cluster-wide default compliance enforcement\nmode (\"enforce\" | \"monitor\"). Per-org config may override it. (RD-1044)", "type": "string" }, "travel_rule_enabled": { "type": "boolean" } }, "type": "object" }, "internal_server.SessionListResponse": { "properties": { "sessions": { "items": { "$ref": "#/components/schemas/internal_server.sessionInfoResponse" }, "type": "array", "uniqueItems": false }, "total": { "type": "integer" } }, "type": "object" }, "internal_server.SessionStatusResponse": { "properties": { "completed": { "type": "boolean" }, "tokens": { "$ref": "#/components/schemas/internal_server.AuthResponse" } }, "type": "object" }, "internal_server.StatusResponse": { "properties": { "methods": { "$ref": "#/components/schemas/internal_server.MethodsStatus" }, "node": { "$ref": "#/components/schemas/internal_server.NodeStatus" }, "proxy": { "$ref": "#/components/schemas/internal_server.ProxyStatus" }, "security": { "$ref": "#/components/schemas/internal_server.SecurityStatus" } }, "type": "object" }, "internal_server.TestRequestInput": { "properties": { "jwt_token": { "type": "string" }, "method": { "type": "string" }, "org_id": { "type": "string" }, "params": { "items": {}, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_server.TestRequestResponse": { "properties": { "error": { "type": "string" }, "identity": { "description": "The identity used for access control", "type": "string" }, "latency_ms": { "type": "integer" }, "result": {} }, "type": "object" }, "internal_server.UserOrgResponse": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "type": "object" }, "internal_server.VerifyLinkRequest": { "properties": { "address": { "type": "string" }, "nonce": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "address", "nonce", "signature" ], "type": "object" }, "internal_server.ViewableAddressesResponse": { "properties": { "disclosed_addresses": { "items": { "$ref": "#/components/schemas/internal_server.DisclosedAddress" }, "type": "array", "uniqueItems": false }, "own_addresses": { "items": { "$ref": "#/components/schemas/internal_server.OwnAddress" }, "type": "array", "uniqueItems": false }, "viewer_did": { "type": "string" }, "viewer_wallet": { "type": "string" } }, "type": "object" }, "internal_server.azureTenantCreateRequest": { "properties": { "auto_provision": { "example": true, "type": "boolean" }, "default_group_id": { "type": "string" }, "default_org_id": { "type": "string" }, "label": { "example": "Contoso", "type": "string" }, "tenant_id": { "example": "11111111-2222-3333-4444-555555555555", "type": "string" } }, "required": [ "tenant_id" ], "type": "object" }, "internal_server.azureTenantListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_db.AllowedAzureTenant" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_server.azureTenantUpdateRequest": { "properties": { "auto_provision": { "example": true, "type": "boolean" }, "default_group_id": { "type": "string" }, "default_org_id": { "type": "string" }, "label": { "example": "Contoso", "type": "string" }, "tenant_id": { "example": "11111111-2222-3333-4444-555555555555", "type": "string" } }, "type": "object" }, "internal_server.contractABIUpdateRequest": { "properties": { "abi": { "example": "[{\"type\":\"event\",\"name\":\"Transfer\",\"inputs\":[]}]", "type": "string" } }, "required": [ "abi" ], "type": "object" }, "internal_server.contractBatchMoveNewGroup": { "properties": { "name": { "example": "Engineering", "type": "string" }, "slug": { "example": "engineering", "type": "string" } }, "required": [ "name", "slug" ], "type": "object" }, "internal_server.contractBatchMoveRequest": { "properties": { "contract_ids": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "delete_empty_auto_groups": { "example": false, "type": "boolean" }, "new_group": { "$ref": "#/components/schemas/internal_server.contractBatchMoveNewGroup" }, "target_group_id": { "example": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d", "type": "string" } }, "required": [ "contract_ids" ], "type": "object" }, "internal_server.contractBatchMoveResponse": { "properties": { "deleted_group_ids": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "moved_count": { "example": 5, "type": "integer" }, "target_group_id": { "example": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d", "type": "string" } }, "type": "object" }, "internal_server.contractClaimRequest": { "properties": { "address": { "example": "0x0000000000000000000000000000000000000001", "type": "string" }, "deployment_tx_hash": { "example": "0x0000000000000000000000000000000000000000000000000000000000000001", "type": "string" }, "name": { "example": "My Token", "type": "string" } }, "required": [ "address", "deployment_tx_hash" ], "type": "object" }, "internal_server.contractClaimResponse": { "properties": { "address": { "example": "0x0000000000000000000000000000000000000001", "type": "string" }, "id": { "example": "11111111-2222-3333-4444-555555555555", "type": "string" }, "name": { "example": "My Token", "type": "string" }, "org_id": { "example": "11111111-2222-3333-4444-555555555555", "type": "string" } }, "type": "object" }, "internal_server.contractCreateRequest": { "properties": { "address": { "example": "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984", "type": "string" }, "metadata": { "additionalProperties": {}, "type": "object" }, "name": { "example": "Uniswap Token", "type": "string" } }, "required": [ "address" ], "type": "object" }, "internal_server.contractEventsAllowDynamicPayloadRequest": { "properties": { "events_allow_dynamic_payload": { "example": false, "type": "boolean" } }, "type": "object" }, "internal_server.contractEventsResponse": { "properties": { "events": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.EventSignature" }, "type": "array", "uniqueItems": false }, "message": { "example": "no ABI registered", "type": "string" } }, "type": "object" }, "internal_server.contractGrantCreateRequest": { "properties": { "event_rules": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.EventRulesField" }, "functions": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.FunctionRule" }, "type": [ "array", "null" ], "uniqueItems": false }, "group_id": { "example": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d", "type": "string" } }, "required": [ "group_id" ], "type": "object" }, "internal_server.contractGrantUpdateRequest": { "properties": { "event_rules": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.EventRulesField" }, "functions": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.FunctionRule" }, "type": [ "array", "null" ], "uniqueItems": false } }, "type": "object" }, "internal_server.contractListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.Contract" }, "type": "array", "uniqueItems": false }, "limit": { "example": 50, "type": "integer" }, "offset": { "example": 0, "type": "integer" }, "total": { "example": 42, "type": "integer" } }, "type": "object" }, "internal_server.contractLookupFullResponse": { "properties": { "contract": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.Contract" }, "grants": { "items": { "$ref": "#/components/schemas/internal_server.contractLookupGrantInfo" }, "type": "array", "uniqueItems": false }, "organization": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.Organization" } }, "type": "object" }, "internal_server.contractLookupGrantInfo": { "properties": { "access": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.GroupAccess" }, "grant": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.ContractGrant" }, "group": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.Group" } }, "type": "object" }, "internal_server.contractSyncCheckResponse": { "properties": { "errors": { "items": { "$ref": "#/components/schemas/internal_server.ContractSyncStatus" }, "type": "array", "uniqueItems": false }, "existing": { "items": { "$ref": "#/components/schemas/internal_server.ContractSyncStatus" }, "type": "array", "uniqueItems": false }, "missing": { "items": { "$ref": "#/components/schemas/internal_server.ContractSyncStatus" }, "type": "array", "uniqueItems": false }, "total": { "example": 3, "type": "integer" } }, "type": "object" }, "internal_server.contractSyncDeleteRequest": { "properties": { "contract_ids": { "items": { "type": "string" }, "type": "array", "uniqueItems": false } }, "required": [ "contract_ids" ], "type": "object" }, "internal_server.contractSyncDeleteResponse": { "properties": { "deleted_addresses": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "deleted_count": { "example": 1, "type": "integer" }, "skipped": { "items": { "$ref": "#/components/schemas/internal_server.contractSyncDeleteSkipped" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_server.contractSyncDeleteSkipped": { "properties": { "id": { "example": "6f1e2d3c-4b5a-6978-8a9b-0c1d2e3f4a5b", "type": "string" }, "reason": { "example": "contract now exists on chain", "type": "string" } }, "type": "object" }, "internal_server.contractUpdateRequest": { "properties": { "metadata": { "additionalProperties": {}, "type": "object" }, "name": { "example": "Renamed contract", "type": "string" } }, "type": "object" }, "internal_server.contractVisibleToUnlockRequest": { "properties": { "allow_visibleto_unlock": { "example": false, "type": "boolean" } }, "required": [ "allow_visibleto_unlock" ], "type": "object" }, "internal_server.dryRunRPCBlock": { "properties": { "method": { "type": "string" }, "params": { "items": {}, "type": "array", "uniqueItems": false } }, "required": [ "method" ], "type": "object" }, "internal_server.dryRunRequest": { "properties": { "rpc": { "$ref": "#/components/schemas/internal_server.dryRunRPCBlock" }, "user_did": { "type": "string" } }, "required": [ "rpc", "user_did" ], "type": "object" }, "internal_server.dryRunResponseDoc": { "properties": { "decision": { "example": "allow", "type": "string" }, "logs_emitted": { "items": {}, "type": "array", "uniqueItems": false }, "logs_visible_to_user": { "items": {}, "type": "array", "uniqueItems": false }, "reason": { "type": "string" }, "response": {}, "trace": {} }, "type": "object" }, "internal_server.ethAddressCollisionsResponse": { "properties": { "collisions": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_db.AddressLinkCollision" }, "type": "array", "uniqueItems": false }, "count": { "example": 0, "type": "integer" } }, "type": "object" }, "internal_server.groupAccessRequest": { "properties": { "allowed_methods": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "claims": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.Claim" }, "type": "array", "uniqueItems": false }, "rpc_api_key": { "type": "string" }, "verbose_errors": { "type": "boolean" } }, "type": "object" }, "internal_server.groupBatchDeletePreviewEntry": { "properties": { "contract_count": { "example": 2, "type": "integer" }, "contracts": { "description": "contract addresses", "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "id": { "example": "6f1e2d3c-0000-0000-0000-000000000001", "type": "string" }, "member_count": { "example": 5, "type": "integer" }, "name": { "example": "engineering", "type": "string" }, "slug": { "example": "engineering", "type": "string" } }, "type": "object" }, "internal_server.groupBatchDeletePreviewResponse": { "properties": { "groups": { "items": { "$ref": "#/components/schemas/internal_server.groupBatchDeletePreviewEntry" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_server.groupBatchDeleteRequest": { "properties": { "group_ids": { "items": { "type": "string" }, "type": "array", "uniqueItems": false } }, "required": [ "group_ids" ], "type": "object" }, "internal_server.groupBatchDeleteResponse": { "properties": { "deleted_count": { "example": 3, "type": "integer" } }, "type": "object" }, "internal_server.groupCreateRequest": { "properties": { "description": { "type": "string" }, "is_org_admin": { "type": "boolean" }, "is_org_readonly_admin": { "type": "boolean" }, "name": { "example": "Engineering", "type": "string" }, "parent_id": { "example": "6f1e2d3c-0000-0000-0000-000000000001", "type": "string" }, "slug": { "example": "engineering", "type": "string" } }, "required": [ "name", "slug" ], "type": "object" }, "internal_server.groupListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.GroupWithAccess" }, "type": "array", "uniqueItems": false }, "limit": { "example": 50, "type": "integer" }, "offset": { "example": 0, "type": "integer" }, "total": { "example": 1, "type": "integer" } }, "type": "object" }, "internal_server.groupUpdateRequest": { "properties": { "description": { "type": "string" }, "is_org_admin": { "type": "boolean" }, "is_org_readonly_admin": { "type": "boolean" }, "name": { "type": "string" } }, "type": "object" }, "internal_server.healthResponse": { "properties": { "status": { "example": "ok", "type": "string" } }, "type": "object" }, "internal_server.linkedAddressEntry": { "properties": { "address": { "example": "0x0000000000000000000000000000000000000001", "type": "string" }, "ens_name": { "example": "alice.eth", "type": "string" }, "ens_resolved_at": { "example": "2026-01-01T00:00:00Z", "type": "string" }, "verified_at": { "example": "2026-01-01T00:00:00Z", "type": "string" } }, "type": "object" }, "internal_server.membershipByDIDRemovalRequest": { "properties": { "did": { "example": "did:example:alice", "type": "string" }, "group_id": { "example": "6f1e2d3c-0000-0000-0000-000000000001", "type": "string" } }, "required": [ "did", "group_id" ], "type": "object" }, "internal_server.membershipByDIDRequest": { "properties": { "did": { "example": "did:example:alice", "type": "string" }, "expires_at": { "example": "2027-01-01T00:00:00Z", "type": "string" }, "group_id": { "example": "6f1e2d3c-0000-0000-0000-000000000001", "type": "string" } }, "required": [ "did", "group_id" ], "type": "object" }, "internal_server.membershipByDIDResponse": { "properties": { "membership": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.UserMembership" }, "user_id": { "example": "6f1e2d3c-0000-0000-0000-000000000002", "type": "string" } }, "type": "object" }, "internal_server.membershipCreateRequest": { "properties": { "expires_at": { "example": "2027-01-01T00:00:00Z", "type": "string" }, "group_id": { "example": "6f1e2d3c-0000-0000-0000-000000000001", "type": "string" } }, "required": [ "group_id" ], "type": "object" }, "internal_server.membershipListItem": { "properties": { "expired": { "type": "boolean" }, "group": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.Group" }, "membership": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.UserMembership" } }, "type": "object" }, "internal_server.oauthAuthorizeJSONResponse": { "properties": { "auth_request": { "additionalProperties": {}, "type": "object" }, "auth_session_id": { "example": "9f2a...41", "type": "string" }, "oauth_session_id": { "example": "3b1e...c7", "type": "string" } }, "type": "object" }, "internal_server.oauthCallbackResponse": { "properties": { "redirect_url": { "example": "https://client.example.com/callback?code=\u003ccode\u003e\u0026state=\u003cstate\u003e", "type": "string" }, "status": { "example": "success", "type": "string" } }, "type": "object" }, "internal_server.oauthMockCompleteResponse": { "properties": { "did": { "example": "did:privado:mock_1717000000000000000", "type": "string" }, "ok": { "example": true, "type": "boolean" } }, "type": "object" }, "internal_server.oauthSessionInfoResponse": { "properties": { "allow_mock": { "example": false, "type": "boolean" }, "auth_request": { "additionalProperties": {}, "type": "object" } }, "type": "object" }, "internal_server.orgCreateRequest": { "properties": { "name": { "example": "ACME Corp", "type": "string" }, "settings": { "additionalProperties": {}, "type": "object" }, "slug": { "example": "acme", "type": "string" } }, "required": [ "name", "slug" ], "type": "object" }, "internal_server.orgListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.Organization" }, "type": "array", "uniqueItems": false }, "limit": { "example": 50, "type": "integer" }, "offset": { "example": 0, "type": "integer" }, "total": { "example": 1, "type": "integer" } }, "type": "object" }, "internal_server.orgUpdateRequest": { "properties": { "name": { "example": "ACME Corp", "type": "string" }, "settings": { "additionalProperties": {}, "type": "object" }, "slug": { "example": "acme", "type": "string" } }, "type": "object" }, "internal_server.rbacUserUpdateRequest": { "properties": { "banned": { "type": "boolean" }, "kyc": { "type": "boolean" }, "metadata": { "additionalProperties": {}, "type": "object" }, "note": { "type": "string" } }, "type": "object" }, "internal_server.sessionInfoResponse": { "properties": { "completed": { "type": "boolean" }, "completed_at": { "type": "string" }, "created_at": { "type": "string" }, "expires_at": { "type": "string" }, "id": { "type": "string" } }, "type": "object" }, "internal_server.sharedInfraInput": { "properties": { "address": { "type": "string" }, "codehash": { "description": "Codehash is optional. Empty / omitted = no codehash pin\n(legacy behaviour: trust by address alone). When supplied it\nmust be a 0x-prefixed lowercase 32-byte hex string. The\nrecommended workflow is to omit on create and use the\n/refresh-codehash endpoint immediately after, which computes\nit server-side from the current bytecode.", "type": "string" }, "description": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "internal_server.sharedInfraListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.SharedInfrastructure" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_server.systemToggleRequest": { "properties": { "enabled": { "description": "pointer so we distinguish \"false\" from \"omitted\"", "type": "boolean" }, "reason": { "type": "string" } }, "required": [ "enabled" ], "type": "object" }, "internal_server.systemToggleResponse": { "properties": { "changed_at": { "type": "string" }, "changed_by": { "type": "string" }, "enabled": { "type": "boolean" }, "env_default": { "type": "boolean" }, "reason": { "type": "string" }, "source": { "description": "\"env\" | \"runtime_override\"", "type": "string" } }, "type": "object" }, "internal_server.systemVersionResponse": { "properties": { "build_time": { "type": "string" }, "commit": { "type": "string" }, "version": { "type": "string" } }, "type": "object" }, "internal_server.testIdentitiesResponse": { "properties": { "identities": { "items": { "$ref": "#/components/schemas/internal_server.testIdentity" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_server.testIdentity": { "properties": { "addresses": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "did": { "example": "did:test:alice", "type": "string" }, "name": { "example": "Alice", "type": "string" }, "note": { "example": "treasury signer", "type": "string" }, "orgs": { "items": { "type": "string" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_server.userLinkedAddressesResponse": { "properties": { "addresses": { "items": { "$ref": "#/components/schemas/internal_server.linkedAddressEntry" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_server.userListItem": { "properties": { "auth_tenant_id": { "description": "Azure AD tenant ID (nil for Privado users)", "type": "string" }, "banned": { "type": "boolean" }, "created_at": { "type": "string" }, "external_id": { "description": "User's DID", "type": "string" }, "groups": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.UserGroupMembership" }, "type": "array", "uniqueItems": false }, "id": { "type": "string" }, "kyc": { "type": "boolean" }, "metadata": { "additionalProperties": {}, "type": "object" }, "note": { "type": "string" }, "updated_at": { "type": "string" } }, "type": "object" }, "internal_server.userListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/internal_server.userListItem" }, "type": "array", "uniqueItems": false }, "limit": { "example": 50, "type": "integer" }, "offset": { "example": 0, "type": "integer" }, "total": { "example": 1, "type": "integer" } }, "type": "object" }, "privacy-proxy_internal_compliance.AddressThresholdOverride": { "properties": { "address": { "description": "lowercased 0x-prefixed", "type": "string" }, "created_at": { "type": "string" }, "id": { "type": "string" }, "note": { "type": "string" }, "org_id": { "type": "string" }, "threshold_fiat": { "type": "number" }, "updated_at": { "type": "string" } }, "type": "object" }, "privacy-proxy_internal_compliance.ComplianceConfig": { "properties": { "created_at": { "type": "string" }, "currency": { "description": "Currency is the per-org fiat currency (usd/eur/chf/gbp/aed) that\nthreshold_fiat is denominated in and that transfers are valued against\n(RD-1158). Per-org so one org's currency choice can never fail-close\nanother org. An empty value resolves to the global base_currency setting,\nthen to \"usd\" (see Server.orgCurrency).", "type": "string" }, "enabled": { "type": "boolean" }, "enforcement_mode": { "$ref": "#/components/schemas/privacy-proxy_internal_compliance.EnforcementMode" }, "id": { "type": "string" }, "org_id": { "type": "string" }, "threshold_fiat": { "type": "number" }, "unknown_price_policy": { "$ref": "#/components/schemas/privacy-proxy_internal_compliance.UnknownPricePolicy" }, "updated_at": { "type": "string" } }, "type": "object" }, "privacy-proxy_internal_compliance.ComplianceLog": { "properties": { "amount_fiat": { "type": "number" }, "amount_wei": { "type": "string" }, "correlation_id": { "type": "string" }, "created_at": { "type": "string" }, "currency": { "type": "string" }, "decision": { "description": "\"allowed\" or \"denied\"", "type": "string" }, "denial_reason": { "type": "string" }, "from_address": { "type": "string" }, "id": { "type": "integer" }, "org_id": { "type": "string" }, "threshold_fiat": { "type": "number" }, "to_address": { "type": "string" }, "token_address": { "type": "string" }, "transfer_type": { "$ref": "#/components/schemas/privacy-proxy_internal_compliance.TransferType" }, "travel_rule_record_id": { "type": "string" }, "user_external_id": { "type": "string" }, "user_id": { "type": "string" }, "would_block": { "description": "WouldBlock marks a monitor-mode violation: the transfer was allowed to\nproceed (Decision=\"allowed\") but WOULD have been blocked under enforce\nmode. DenialReason carries the would-have-blocked reason. Lets auditors\ndistinguish a monitored violation from a genuinely-compliant allow.", "type": "boolean" } }, "type": "object" }, "privacy-proxy_internal_compliance.EnforcementMode": { "description": "EnforcementMode is enforce (block, default) or monitor (allow + record)\nfor monitor-eligible violations. An empty value resolves to the cluster\ndefault (COMPLIANCE_DEFAULT_MODE), which itself defaults to enforce.", "enum": [ "enforce", "monitor" ], "type": "string", "x-enum-varnames": [ "EnforcementEnforce", "EnforcementMonitor" ] }, "privacy-proxy_internal_compliance.SanctionedAddress": { "properties": { "added_by_user_id": { "type": "string" }, "address": { "type": "string" }, "created_at": { "type": "string" }, "id": { "type": "string" }, "org_id": { "description": "nil = global", "type": "string" }, "reason": { "type": "string" }, "source": { "type": "string" }, "updated_at": { "type": "string" } }, "type": "object" }, "privacy-proxy_internal_compliance.TokenPrice": { "properties": { "coingecko_id": { "description": "when set, price resolves from system_token_prices", "type": "string" }, "created_at": { "type": "string" }, "decimals": { "type": "integer" }, "id": { "type": "string" }, "org_id": { "type": "string" }, "price_fiat": { "description": "price in the active base currency", "type": "number" }, "prices_by_currency": { "additionalProperties": { "type": "number" }, "description": "all manually-set currency prices", "type": "object" }, "symbol": { "type": "string" }, "token_address": { "description": "\"native\" for ETH, or lowercase 0x-prefixed contract address", "type": "string" }, "updated_at": { "type": "string" }, "updated_by_user_id": { "type": "string" } }, "type": "object" }, "privacy-proxy_internal_compliance.TransferType": { "enum": [ "eth", "erc20" ], "type": "string", "x-enum-varnames": [ "TransferTypeETH", "TransferTypeERC20" ] }, "privacy-proxy_internal_compliance.TravelRuleRecord": { "properties": { "amount_fiat": { "type": "number" }, "amount_wei": { "type": "string" }, "beneficiary_address": { "type": "string" }, "beneficiary_data": { "additionalProperties": {}, "type": "object" }, "created_at": { "type": "string" }, "currency": { "type": "string" }, "expires_at": { "type": "string" }, "id": { "type": "string" }, "org_id": { "type": "string" }, "originator_data": { "additionalProperties": {}, "type": "object" }, "originator_external_id": { "type": "string" }, "originator_user_id": { "type": "string" }, "token_address": { "type": "string" }, "transfer_type": { "$ref": "#/components/schemas/privacy-proxy_internal_compliance.TransferType" }, "used_at": { "type": "string" }, "used_tx_hash": { "type": "string" }, "warning": { "description": "non-persisted, advisory only", "type": "string" } }, "type": "object" }, "privacy-proxy_internal_compliance.UnknownPricePolicy": { "enum": [ "allowed", "forbidden" ], "type": "string", "x-enum-varnames": [ "UnknownPriceAllowed", "UnknownPriceForbidden" ] }, "privacy-proxy_internal_db.AccessLog": { "properties": { "correlation_id": { "type": "string" }, "created_at": { "type": "string" }, "denial_reason": { "description": "DenialReason is the curated reason code for a denied request (RD-1137;\nsee server.denial_reasons). NULL for successful or unclassified requests.", "type": "string" }, "entry_hash": { "type": "string" }, "external_id": { "type": "string" }, "hash_format_version": { "type": "integer" }, "id": { "type": "integer" }, "ip_address": { "type": "string" }, "method": { "type": "string" }, "org_id": { "description": "OrgID is the organization the entry-point access decision resolved\nagainst (RD-1135). NULL for pre-migration rows and for requests with\nno resolved org (anonymous / org-free metadata methods); such rows are\nvisible only to super-admin callers.", "type": "string" }, "request_params": { "items": { "type": "integer" }, "type": "array", "uniqueItems": false }, "response_status": { "type": "integer" }, "status_code": { "type": "integer" } }, "type": "object" }, "privacy-proxy_internal_db.AddressLinkCollision": { "properties": { "dids": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "eth_address": { "type": "string" }, "link_types": { "items": { "type": "string" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "privacy-proxy_internal_db.AllowedAzureTenant": { "properties": { "auto_provision": { "type": "boolean" }, "created_at": { "type": "string" }, "default_group_id": { "type": "string" }, "default_org_id": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "tenant_id": { "type": "string" }, "updated_at": { "type": "string" } }, "type": "object" }, "privacy-proxy_internal_disclosure.ActivityLogEntry": { "properties": { "created_at": { "type": "string" }, "id": { "type": "integer" }, "ip_address": { "type": "string" }, "method": { "type": "string" }, "status_code": { "type": "integer" } }, "type": "object" }, "privacy-proxy_internal_disclosure.ActivitySummary": { "properties": { "date_range": { "$ref": "#/components/schemas/privacy-proxy_internal_disclosure.DateRange" }, "failed_count": { "type": "integer" }, "generated_at": { "type": "string" }, "method_breakdown": { "additionalProperties": { "type": "integer" }, "description": "method -\u003e count", "type": "object" }, "successful_count": { "type": "integer" }, "total_requests": { "type": "integer" }, "unique_method_count": { "type": "integer" } }, "type": "object" }, "privacy-proxy_internal_disclosure.DataSummary": { "properties": { "addresses": { "description": "Addresses that were accessed", "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "date_range": { "$ref": "#/components/schemas/privacy-proxy_internal_disclosure.DateRange" }, "methods": { "description": "Methods that were accessed", "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "record_count": { "type": "integer" } }, "type": "object" }, "privacy-proxy_internal_disclosure.DateRange": { "description": "Time period", "properties": { "end": { "type": "string" }, "start": { "type": "string" } }, "type": "object" }, "privacy-proxy_internal_disclosure.DisclosureLevel": { "description": "How much address detail to reveal", "enum": [ "full", "pseudonymous", "redacted" ], "example": "pseudonymous", "type": "string", "x-enum-varnames": [ "DisclosureFull", "DisclosurePseudonymous", "DisclosureRedacted" ] }, "privacy-proxy_internal_disclosure.DisclosureListResult": { "properties": { "limit": { "description": "Limit is the limit that was applied", "type": "integer" }, "offset": { "description": "Offset is the offset that was applied", "type": "integer" }, "requests": { "description": "Requests is the list of matching disclosure requests", "items": { "$ref": "#/components/schemas/privacy-proxy_internal_disclosure.RequestWithDetails" }, "type": "array", "uniqueItems": false }, "total": { "description": "Total is the total count of matching records (for pagination)", "type": "integer" } }, "type": "object" }, "privacy-proxy_internal_disclosure.Event": { "properties": { "accessed_at": { "type": "string" }, "action": { "$ref": "#/components/schemas/privacy-proxy_internal_disclosure.EventAction" }, "data_summary": { "$ref": "#/components/schemas/privacy-proxy_internal_disclosure.DataSummary" }, "grant_id": { "type": "string" }, "id": { "type": "integer" }, "resource_type": { "$ref": "#/components/schemas/privacy-proxy_internal_disclosure.ResourceType" }, "viewer_ip": { "type": "string" }, "viewer_user_id": { "type": "string" } }, "type": "object" }, "privacy-proxy_internal_disclosure.EventAction": { "enum": [ "view_logs", "view_transactions", "view_summary", "export_report" ], "type": "string", "x-enum-varnames": [ "ActionViewLogs", "ActionViewTransactions", "ActionViewSummary", "ActionExportReport" ] }, "privacy-proxy_internal_disclosure.Grant": { "properties": { "expires_at": { "type": "string" }, "granted_at": { "type": "string" }, "id": { "type": "string" }, "request_id": { "type": "string" }, "revoked_at": { "type": "string" }, "revoked_reason": { "type": "string" }, "scope": { "$ref": "#/components/schemas/privacy-proxy_internal_disclosure.Scope" } }, "type": "object" }, "privacy-proxy_internal_disclosure.GrantListResult": { "properties": { "grants": { "description": "Grants is the list of matching grants with their requests", "items": { "$ref": "#/components/schemas/privacy-proxy_internal_disclosure.GrantWithRequest" }, "type": "array", "uniqueItems": false }, "limit": { "description": "Limit is the limit that was applied", "type": "integer" }, "offset": { "description": "Offset is the offset that was applied", "type": "integer" }, "total": { "description": "Total is the total count of matching records (for pagination)", "type": "integer" } }, "type": "object" }, "privacy-proxy_internal_disclosure.GrantWithRequest": { "properties": { "grant": { "$ref": "#/components/schemas/privacy-proxy_internal_disclosure.Grant" }, "request": { "$ref": "#/components/schemas/privacy-proxy_internal_disclosure.Request" } }, "type": "object" }, "privacy-proxy_internal_disclosure.Report": { "properties": { "expires_at": { "type": "string" }, "generated_at": { "type": "string" }, "grant_id": { "type": "string" }, "id": { "type": "string" }, "report_data": { "additionalProperties": {}, "type": "object" }, "report_type": { "$ref": "#/components/schemas/privacy-proxy_internal_disclosure.ReportType" } }, "type": "object" }, "privacy-proxy_internal_disclosure.ReportType": { "enum": [ "activity_summary", "sanctions_check", "compliance_report" ], "type": "string", "x-enum-varnames": [ "ReportActivitySummary", "ReportSanctionsCheck", "ReportCompliance" ] }, "privacy-proxy_internal_disclosure.Request": { "properties": { "decided_at": { "type": "string" }, "decided_by_user_id": { "type": "string" }, "decision_reason": { "type": "string" }, "expires_at": { "description": "When request expires if not acted upon", "type": "string" }, "id": { "type": "string" }, "legal_basis": { "description": "GDPR article, court order, etc.", "type": "string" }, "org_id": { "type": "string" }, "reason": { "type": "string" }, "requested_at": { "type": "string" }, "requester_did": { "description": "DID of authorized viewer (for block explorer auth)", "type": "string" }, "requester_user_id": { "description": "Who is requesting (may be external)", "type": "string" }, "scope": { "$ref": "#/components/schemas/privacy-proxy_internal_disclosure.Scope" }, "status": { "$ref": "#/components/schemas/privacy-proxy_internal_disclosure.RequestStatus" }, "target_user_id": { "description": "Whose data is being requested", "type": "string" } }, "type": "object" }, "privacy-proxy_internal_disclosure.RequestStatus": { "enum": [ "pending", "approved", "rejected", "expired", "revoked" ], "type": "string", "x-enum-varnames": [ "StatusPending", "StatusApproved", "StatusRejected", "StatusExpired", "StatusRevoked" ] }, "privacy-proxy_internal_disclosure.RequestWithDetails": { "properties": { "active_grant_id": { "type": "string" }, "decided_by_did": { "type": "string" }, "request": { "$ref": "#/components/schemas/privacy-proxy_internal_disclosure.Request" }, "requester_did": { "type": "string" }, "target_did": { "type": "string" } }, "type": "object" }, "privacy-proxy_internal_disclosure.ResourceType": { "enum": [ "access_logs", "transactions", "summary", "report" ], "type": "string", "x-enum-varnames": [ "ResourceAccessLogs", "ResourceTransactions", "ResourceSummary", "ResourceReport" ] }, "privacy-proxy_internal_disclosure.Scope": { "properties": { "addresses": { "description": "Specific contract addresses", "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "date_range": { "$ref": "#/components/schemas/privacy-proxy_internal_disclosure.DateRange" }, "disclosure_level": { "$ref": "#/components/schemas/privacy-proxy_internal_disclosure.DisclosureLevel" }, "methods": { "description": "Specific RPC methods to disclose", "items": { "type": "string" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "privacy-proxy_internal_explorer.AddressStats": { "properties": { "address": { "type": "string" }, "firstSeen": { "type": "integer" }, "internalTxCount": { "type": "integer" }, "isContract": { "type": "boolean" }, "lastSeen": { "type": "integer" }, "tokenTransferCount": { "type": "integer" }, "txCount": { "type": "integer" }, "updatedAt": { "type": "string" } }, "type": "object" }, "privacy-proxy_internal_explorer.Balance": { "properties": { "address": { "type": "string" }, "balance": { "type": "string" }, "blockNumber": { "type": "integer" }, "tokenAddress": { "type": "string" } }, "type": "object" }, "privacy-proxy_internal_explorer.Block": { "properties": { "baseFeePerGas": { "type": "integer" }, "createdAt": { "type": "string" }, "difficulty": { "type": "string" }, "extraData": { "type": "string" }, "gasLimit": { "type": "integer" }, "gasUsed": { "type": "integer" }, "hash": { "type": "string" }, "miner": { "type": "string" }, "nonce": { "type": "string" }, "number": { "type": "integer" }, "parentHash": { "type": "string" }, "receiptsRoot": { "type": "string" }, "stateRoot": { "type": "string" }, "timestamp": { "type": "integer" }, "totalDifficulty": { "type": "string" }, "transactionCount": { "type": "integer" }, "transactionsRoot": { "type": "string" } }, "type": "object" }, "privacy-proxy_internal_explorer.ChainStats": { "properties": { "avgBlockTime": { "type": "number" }, "privacyEnabled": { "type": "boolean" }, "totalAddresses": { "type": "integer" }, "totalBlocks": { "type": "integer" }, "totalTokens": { "type": "integer" }, "totalTransactions": { "type": "integer" } }, "type": "object" }, "privacy-proxy_internal_explorer.Contract": { "properties": { "abi": { "items": { "type": "integer" }, "type": "array", "uniqueItems": false }, "address": { "type": "string" }, "blockNumber": { "type": "integer" }, "bytecode": { "type": "string" }, "bytecodeHash": { "type": "string" }, "compilerVersion": { "type": "string" }, "constructorArgs": { "type": "string" }, "contractName": { "type": "string" }, "createdAt": { "type": "string" }, "creationTx": { "type": "string" }, "creator": { "type": "string" }, "evmVersion": { "type": "string" }, "isVerified": { "type": "boolean" }, "licenseType": { "type": "string" }, "optimizationRuns": { "type": "integer" }, "optimizationUsed": { "type": "boolean" }, "sourceCode": { "type": "string" } }, "type": "object" }, "privacy-proxy_internal_explorer.IndexerProgress": { "properties": { "backfillComplete": { "type": "boolean" }, "id": { "type": "integer" }, "maxFetchedBlock": { "type": "integer" }, "minFetchedBlock": { "type": "integer" }, "updatedAt": { "type": "string" } }, "type": "object" }, "privacy-proxy_internal_explorer.InternalTransaction": { "properties": { "addressMetadata": { "additionalProperties": { "$ref": "#/components/schemas/privacy-proxy_internal_explorer.VisibilityReason" }, "type": "object" }, "blockNumber": { "type": "integer" }, "callType": { "type": "string" }, "error": { "type": "string" }, "from": { "type": "string" }, "gas": { "type": "integer" }, "gasUsed": { "type": "integer" }, "id": { "type": "integer" }, "input": { "type": "string" }, "output": { "type": "string" }, "timestamp": { "type": "integer" }, "to": { "type": "string" }, "traceAddress": { "type": "string" }, "txHash": { "type": "string" }, "value": { "type": "string" } }, "type": "object" }, "privacy-proxy_internal_explorer.Log": { "properties": { "address": { "type": "string" }, "addressMetadata": { "additionalProperties": { "$ref": "#/components/schemas/privacy-proxy_internal_explorer.VisibilityReason" }, "type": "object" }, "blockNumber": { "type": "integer" }, "data": { "type": "string" }, "id": { "type": "integer" }, "logIndex": { "type": "integer" }, "removed": { "type": "boolean" }, "timestamp": { "type": "integer" }, "topic0": { "type": "string" }, "topic1": { "type": "string" }, "topic2": { "type": "string" }, "topic3": { "type": "string" }, "txHash": { "type": "string" } }, "type": "object" }, "privacy-proxy_internal_explorer.SearchSuggestion": { "properties": { "label": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" } }, "type": "object" }, "privacy-proxy_internal_explorer.SyncStatus": { "properties": { "isSyncing": { "type": "boolean" }, "lastIndexedBlock": { "type": "integer" }, "updatedAt": { "type": "string" } }, "type": "object" }, "privacy-proxy_internal_explorer.Token": { "properties": { "address": { "type": "string" }, "blockNumber": { "type": "integer" }, "createdAt": { "type": "string" }, "creationTx": { "type": "string" }, "decimals": { "type": "integer" }, "holderCount": { "type": "integer" }, "iconUrl": { "type": "string" }, "l1Address": { "type": "string" }, "name": { "type": "string" }, "offChainUpdatedAt": { "type": "string" }, "symbol": { "type": "string" }, "tokenType": { "type": "string" }, "totalSupply": { "type": "string" }, "transferCount": { "type": "integer" }, "usdPrice": { "type": "number" } }, "type": "object" }, "privacy-proxy_internal_explorer.TokenHolder": { "properties": { "address": { "type": "string" }, "balance": { "type": "string" }, "isContract": { "type": "boolean" }, "percentage": { "type": "number" } }, "type": "object" }, "privacy-proxy_internal_explorer.TokenTransfer": { "properties": { "addressMetadata": { "additionalProperties": { "$ref": "#/components/schemas/privacy-proxy_internal_explorer.VisibilityReason" }, "type": "object" }, "blockNumber": { "type": "integer" }, "from": { "type": "string" }, "id": { "type": "integer" }, "isInternal": { "type": "boolean" }, "logIndex": { "type": "integer" }, "timestamp": { "type": "integer" }, "to": { "type": "string" }, "tokenAddress": { "type": "string" }, "tokenId": { "type": "string" }, "tokenType": { "type": "string" }, "transferType": { "type": "string" }, "txHash": { "type": "string" }, "value": { "type": "string" } }, "type": "object" }, "privacy-proxy_internal_explorer.Transaction": { "properties": { "addressMetadata": { "additionalProperties": { "$ref": "#/components/schemas/privacy-proxy_internal_explorer.VisibilityReason" }, "type": "object" }, "blockNumber": { "type": "integer" }, "blockTimestamp": { "type": "integer" }, "contractAddress": { "type": "string" }, "createdAt": { "type": "string" }, "error": { "type": "string" }, "from": { "type": "string" }, "gasLimit": { "type": "integer" }, "gasPrice": { "type": "integer" }, "gasUsed": { "type": "integer" }, "hash": { "type": "string" }, "inputData": { "type": "string" }, "maxFeePerGas": { "type": "integer" }, "maxPriorityFeePerGas": { "type": "integer" }, "nonce": { "type": "integer" }, "revertReason": { "type": "string" }, "status": { "type": "integer" }, "to": { "type": "string" }, "tokenTransferCount": { "type": "integer" }, "txCategories": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "txIndex": { "type": "integer" }, "txType": { "type": "integer" }, "value": { "type": "string" } }, "type": "object" }, "privacy-proxy_internal_explorer.TxHistoryPoint": { "properties": { "count": { "type": "integer" }, "timestamp": { "type": "integer" } }, "type": "object" }, "privacy-proxy_internal_explorer.VisibilityReason": { "enum": [ "own_address", "disclosure_grant", "public_address", "no_access", "rbac_group_member", "participant_override", "visible_to_grant" ], "type": "string", "x-enum-varnames": [ "ReasonOwnAddress", "ReasonDisclosureGrant", "ReasonPublicAddress", "ReasonNoAccess", "ReasonRBACGroupMember", "ReasonParticipantOverride", "ReasonVisibleToGrant" ] }, "privacy-proxy_internal_rbac.AccessCheckRequest": { "properties": { "function_selector": { "description": "First 4 bytes of calldata (e.g., \"0xa9059cbb\")", "type": "string" }, "method": { "description": "Original JSON-RPC method name (used for RBAC allowlist)", "type": "string" }, "org_id": { "description": "Optional org ID for explicit org selection", "type": "string" }, "org_slug": { "description": "Optional org slug (deprecated, use OrgID)", "type": "string" }, "params": { "description": "JSON-RPC params for Multicall detection", "items": {}, "type": "array", "uniqueItems": false }, "required_claims": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.Claim" }, "type": "array", "uniqueItems": false }, "target_address": { "description": "Target address (contract or EOA)", "type": "string" }, "user_external_id": { "type": "string" } }, "type": "object" }, "privacy-proxy_internal_rbac.AccessCheckResult": { "properties": { "allowed": { "type": "boolean" }, "auth_required": { "description": "True when denial is due to missing authentication (401 vs 403)", "type": "boolean" }, "claims": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.Claim" }, "type": "array", "uniqueItems": false }, "org_id": { "description": "Resolved organization ID", "type": "string" }, "reason": { "type": "string" }, "user_id": { "description": "Internal user ID (UUID)", "type": "string" } }, "type": "object" }, "privacy-proxy_internal_rbac.CacheStats": { "properties": { "entries": { "type": "integer" }, "expired_pending": { "type": "integer" }, "max_entries": { "type": "integer" } }, "type": "object" }, "privacy-proxy_internal_rbac.Claim": { "enum": [ "admin", "upgrade", "deploy" ], "type": "string", "x-enum-comments": { "ClaimAdmin": "Full control — implies deploy + upgrade", "ClaimDeploy": "Can deploy new contracts (contract creation transactions)", "ClaimUpgrade": "Can upgrade proxy contracts" }, "x-enum-varnames": [ "ClaimAdmin", "ClaimUpgrade", "ClaimDeploy" ] }, "privacy-proxy_internal_rbac.Contract": { "properties": { "abi": { "description": "Contract ABI JSON for function-level access control", "type": "string" }, "address": { "description": "lowercase 0x-prefixed", "type": "string" }, "allow_visibleto_unlock": { "description": "AllowVisibleToUnlock: when true, per-tx visibleTo lists act as a\nper-event opt-in unlock for eligible viewers (RD-874). False\npreserves the pre-RD-874 additive-only behaviour. Admin-only via\nthe dedicated PATCH endpoint; never settable by sendTransaction\nor by non-admin contract create/update calls.", "type": "boolean" }, "created_at": { "type": "string" }, "deployed_at": { "type": "string" }, "deployed_by_user_id": { "type": "string" }, "events_allow_dynamic_payload": { "description": "EventsAllowDynamicPayload: when true, RedactLogs /\nFilterEventLogs pass through events with dynamic non-indexed\nparameters (`bytes`, `string`, dynamic arrays / structs)\nwithout dropping for non-Full viewers (M15 opt-out, security\naudit follow-up to RD-915). Default false — close-by-default\nbehaviour: events whose payload could embed foreign-org\naddresses are dropped for any viewer who didn't earn Full\nvisibility via admin claim, participant override, or\nvisibleTo unlock. Admin-only via the dedicated PUT endpoint.", "type": "boolean" }, "id": { "type": "string" }, "metadata": { "additionalProperties": {}, "type": "object" }, "name": { "type": "string" }, "org_id": { "type": "string" }, "updated_at": { "type": "string" } }, "type": "object" }, "privacy-proxy_internal_rbac.ContractAccess": { "properties": { "claims": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.Claim" }, "type": "array", "uniqueItems": false }, "event_rules": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.EventRulesField" }, "functions": { "description": "nil = all functions allowed", "items": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.FunctionRule" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "privacy-proxy_internal_rbac.ContractGrant": { "properties": { "contract_id": { "type": "string" }, "created_at": { "type": "string" }, "event_rules": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.EventRulesField" }, "functions": { "description": "No omitempty: a non-nil empty slice ([]) means \"deny all functions\"\n(events-only grant) and MUST be distinguishable in the API response from\nnil (\"all functions\"). Mirrors EventRules below, which is likewise always\nserialized so the dashboard can tell none/all/specific apart.", "items": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.FunctionRule" }, "type": [ "array", "null" ], "uniqueItems": false }, "group_id": { "type": "string" }, "id": { "type": "string" }, "updated_at": { "type": "string" } }, "type": "object" }, "privacy-proxy_internal_rbac.ContractGrantSummary": { "properties": { "count": { "type": "integer" }, "groups": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.GroupSummary" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "privacy-proxy_internal_rbac.EffectivePermissions": { "properties": { "allowed_methods": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "claims": { "description": "User's capabilities from groups", "items": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.Claim" }, "type": "array", "uniqueItems": false }, "computed_at": { "type": "string" }, "contract_access": { "additionalProperties": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.ContractAccess" }, "description": "address -\u003e access", "type": "object" }, "expires_at": { "type": "string" }, "id": { "type": "string" }, "org_id": { "type": "string" }, "user_id": { "type": "string" } }, "type": "object" }, "privacy-proxy_internal_rbac.EventInput": { "properties": { "indexed": { "type": "boolean" }, "name": { "type": "string" }, "type": { "description": "ABI type string (e.g. \"address\", \"uint256\")", "type": "string" } }, "type": "object" }, "privacy-proxy_internal_rbac.EventRule": { "properties": { "name": { "description": "human-readable event name, from ABI", "type": "string" }, "param_rules": { "description": "optional \"self\" constraints (reuse existing ParamRule)", "items": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.ParamRule" }, "type": "array", "uniqueItems": false }, "topic0": { "description": "keccak256(EventName(paramTypes)) — 32-byte hex with 0x prefix", "type": "string" } }, "type": "object" }, "privacy-proxy_internal_rbac.EventRulesField": { "description": "null = deny, wildcard = all events, allowlist = specific events", "properties": { "rules": { "description": "allowlist rules; only meaningful when Wildcard is false", "items": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.EventRule" }, "type": "array" }, "wildcard": { "description": "true when the JSON value is the string \"*\"", "type": "boolean" } }, "type": "object" }, "privacy-proxy_internal_rbac.EventSignature": { "properties": { "default_param_rules": { "description": "suggested \"self\" constraint for each address-typed input", "items": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.ParamRule" }, "type": "array", "uniqueItems": false }, "inputs": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.EventInput" }, "type": "array", "uniqueItems": false }, "name": { "description": "e.g. \"Transfer\"", "type": "string" }, "signature": { "description": "e.g. \"Transfer(address,address,uint256)\"", "type": "string" }, "topic0": { "description": "keccak256 of signature, hex-encoded with 0x prefix", "type": "string" } }, "type": "object" }, "privacy-proxy_internal_rbac.FunctionRule": { "properties": { "param_rules": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.ParamRule" }, "type": "array", "uniqueItems": false }, "selector": { "type": "string" } }, "type": "object" }, "privacy-proxy_internal_rbac.Group": { "properties": { "auto_created": { "description": "Deprecated: always false for new groups. Column retained in DB for expand-only migration policy.", "type": "boolean" }, "created_at": { "type": "string" }, "depth": { "type": "integer" }, "description": { "type": "string" }, "id": { "type": "string" }, "is_org_admin": { "description": "If true, members get all claims on all contracts in the org", "type": "boolean" }, "is_org_readonly_admin": { "description": "If true, members can read all admin endpoints in the org but cannot mutate (RD-866)", "type": "boolean" }, "is_system": { "description": "Seeded, identity-immutable rows (e.g. anonymous, RD-870)", "type": "boolean" }, "name": { "type": "string" }, "org_id": { "type": "string" }, "parent_id": { "type": "string" }, "path": { "description": "Materialized path (e.g., \"root.engineering.devops\")", "type": "string" }, "slug": { "type": "string" }, "updated_at": { "type": "string" } }, "type": "object" }, "privacy-proxy_internal_rbac.GroupAccess": { "properties": { "allowed_methods": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "claims": { "description": "Operational claims: deploy, upgrade, admin", "items": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.Claim" }, "type": "array", "uniqueItems": false }, "created_at": { "type": "string" }, "effective_claims": { "description": "Computed fields (not stored in DB, populated by handlers for child groups)", "items": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.Claim" }, "type": "array", "uniqueItems": false }, "group_id": { "type": "string" }, "id": { "type": "string" }, "narrowed_by_parent": { "type": "boolean" }, "rpc_api_key": { "description": "API key for upstream RPC proxy authentication", "type": "string" }, "updated_at": { "type": "string" }, "verbose_errors": { "description": "RD-1137 Part A: members get curated reason codes on the wire for denials", "type": "boolean" } }, "type": "object" }, "privacy-proxy_internal_rbac.GroupSummary": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "privacy-proxy_internal_rbac.GroupWithAccess": { "properties": { "access": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.GroupAccess" }, "group": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.Group" } }, "type": "object" }, "privacy-proxy_internal_rbac.MembershipSource": { "enum": [ "admin", "zk_attested" ], "type": "string", "x-enum-varnames": [ "MembershipSourceAdmin", "MembershipSourceZKAttested" ] }, "privacy-proxy_internal_rbac.Organization": { "properties": { "created_at": { "type": "string" }, "id": { "type": "string" }, "is_system": { "description": "Seeded, identity-immutable rows (e.g. anonymous, RD-870)", "type": "boolean" }, "name": { "type": "string" }, "settings": { "additionalProperties": {}, "type": "object" }, "slug": { "type": "string" }, "updated_at": { "type": "string" } }, "type": "object" }, "privacy-proxy_internal_rbac.ParamRule": { "properties": { "index": { "description": "ABI parameter position (0-based)", "type": "integer" }, "must_be": { "description": "\"self\" (caller's address) or \"0x...\" (literal hex value)", "type": "string" } }, "type": "object" }, "privacy-proxy_internal_rbac.SharedInfrastructure": { "properties": { "address": { "description": "lowercase 0x-prefixed address", "type": "string" }, "codehash": { "description": "M5: optional codehash pin", "type": "string" }, "created_at": { "type": "string" }, "description": { "description": "Description of the contract", "type": "string" }, "name": { "description": "Human-readable name (e.g., \"Uniswap V3 Router\")", "type": "string" } }, "type": "object" }, "privacy-proxy_internal_rbac.User": { "properties": { "auth_tenant_id": { "description": "Azure AD tenant ID (nil for Privado users)", "type": "string" }, "banned": { "type": "boolean" }, "created_at": { "type": "string" }, "external_id": { "description": "User's DID", "type": "string" }, "id": { "type": "string" }, "kyc": { "type": "boolean" }, "metadata": { "additionalProperties": {}, "type": "object" }, "note": { "type": "string" }, "updated_at": { "type": "string" } }, "type": "object" }, "privacy-proxy_internal_rbac.UserGroupMembership": { "properties": { "group_id": { "type": "string" }, "is_org_admin": { "type": "boolean" }, "name": { "type": "string" }, "org_id": { "type": "string" }, "slug": { "type": "string" } }, "type": "object" }, "privacy-proxy_internal_rbac.UserMembership": { "properties": { "created_at": { "type": "string" }, "expires_at": { "type": "string" }, "group_id": { "type": "string" }, "id": { "type": "string" }, "source": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.MembershipSource" }, "updated_at": { "type": "string" }, "user_id": { "type": "string" }, "zk_credential_ref": { "type": "string" } }, "type": "object" }, "protocol.AuthorizationRequestMessage": { "properties": { "attachments": { "items": { "$ref": "#/components/schemas/iden3comm.Attachment" }, "type": "array", "uniqueItems": false }, "body": { "$ref": "#/components/schemas/protocol.AuthorizationRequestMessageBody" }, "created_time": { "type": "integer" }, "expires_time": { "type": "integer" }, "from": { "type": "string" }, "id": { "type": "string" }, "thid": { "type": "string" }, "to": { "type": "string" }, "typ": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "protocol.AuthorizationRequestMessageBody": { "properties": { "accept": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "callbackUrl": { "type": "string" }, "did_doc": { "items": { "type": "integer" }, "type": "array", "uniqueItems": false }, "message": { "type": "string" }, "reason": { "type": "string" }, "scope": { "items": { "$ref": "#/components/schemas/protocol.ZeroKnowledgeProofRequest" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "protocol.ZeroKnowledgeProofRequest": { "properties": { "circuitID": { "type": "string" }, "extendedID": { "$ref": "#/components/schemas/big.Int" }, "id": { "type": "integer" }, "optional": { "type": "boolean" }, "params": { "additionalProperties": {}, "type": "object" }, "query": { "additionalProperties": {}, "type": "object" } }, "type": "object" } }, "securitySchemes": { "AdminToken": { "description": "Admin API token (full admin, or the restricted operator token). Admin endpoints additionally require a private-network source address.", "in": "header", "name": "X-Admin-Token", "type": "apiKey" }, "BearerAuth": { "bearerFormat": "JWT", "description": "JWT issued by the auth endpoints, sent as `Authorization: Bearer \u003ctoken\u003e`.", "scheme": "bearer", "type": "http" } } }, "externalDocs": { "description": "", "url": "" }, "info": { "contact": { "name": "Gateway.fm", "url": "https://gateway.fm" }, "description": "REST control-plane and data API of the Open Privacy Suite: authentication (Privado ID wallet flow, Azure AD), ETH address linking, user profile and disclosure, RBAC / compliance / system administration, the block-explorer data API, and the proxied Ethereum JSON-RPC endpoint.\n\n**Authentication.** User endpoints take a Bearer JWT issued by the auth endpoints (`Authorization: Bearer \u003ctoken\u003e`). `/api/v1/admin/*` requires the `X-Admin-Token` header and is additionally reachable only from private-network addresses. `/api/v1/explorer/*` serves the explorer backend and is private-network only.\n\n**Aliases.** Every `/api/v1/eth/*` endpoint is also mounted at `/eth/*`; the auth endpoints are also mounted at the root (`/auth/...`, `/refresh`, `/revoke`, `/introspect`). Legacy unversioned `/api/*` mounts are deprecated and respond with an `X-Deprecated` header. Aliases are intentionally not listed as separate operations. `POST /` is the same operation as `POST /rpc`.\n\n**Dev-only.** A small number of operations exist only in non-production builds and say so in their descriptions.", "title": "Open Privacy Suite REST API", "version": "1.0" }, "openapi": "3.1.0", "paths": { "/api/v1/admin/access/check": { "post": { "description": "Evaluates whether a given user (by external DID) would be allowed to call a method against a target in an organization, returning the resolver's decision and reason. For a tier-2 org-admin JWT the probe is clamped to the caller's scope: the target org must be specified and in scope, and the probed user must share an org with the caller — this prevents the endpoint from being a cluster-wide permission-map oracle. Tenant-confidential: rejected for the operator token (403).", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.AccessCheckRequest", "description": "access-check request", "summary": "request" } ] } } }, "description": "access-check request", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.AccessCheckResult" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid request body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, target org/user outside the caller's scope (opaque), or operator token (tenant data not readable)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Check access", "tags": [ "Admin: RBAC" ] } }, "/api/v1/admin/audit-logs": { "get": { "description": "Returns RBAC audit-log entries. At least one of resource_type or actor_id must be supplied to avoid unbounded scans; resource_id further narrows a resource_type query. A super-admin sees all entries; a tier-2 org-admin JWT receives only entries whose resource lives in an org it administers (filtered in SQL, so cardinality is not an enumeration oracle). Tenant-confidential: rejected for the operator token (403).", "parameters": [ { "description": "Filter by resource type (required unless actor_id is given)", "in": "query", "name": "resource_type", "schema": { "type": "string" } }, { "description": "Further narrow a resource_type query to one resource", "in": "query", "name": "resource_id", "schema": { "type": "string" } }, { "description": "Filter by actor (required unless resource_type is given)", "in": "query", "name": "actor_id", "schema": { "type": "string" } }, { "description": "Max rows to return (default 100, max 1000)", "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "description": "Rows to skip for pagination (default 0)", "in": "query", "name": "offset", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/internal_server.AuditLogEntryDoc" }, "type": "array" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "at least one filter (resource_type or actor_id) is required" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, or operator token (tenant data not readable)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "List RBAC audit logs", "tags": [ "Admin: RBAC" ] } }, "/api/v1/admin/azure-tenants": { "get": { "description": "Lists the Azure AD tenants permitted to authenticate, with their default org/group and auto-provision settings. Super-admin token only — the entries reveal the cluster's SSO topology, so org admins cannot read them.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.azureTenantListResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "super-admin token required" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "List Azure AD tenants", "tags": [ "Admin: shared infrastructure" ] }, "post": { "description": "Allowlists an Azure AD tenant so its users may authenticate, with an optional default org/group and auto-provisioning. tenant_id must be a UUID; a default_group_id must belong to default_org_id and must not be an org-admin or readonly-admin group (so SSO cannot auto-mint org admins). Super-admin token only — this is a cluster-wide primitive; the change is audit-logged.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.azureTenantCreateRequest", "description": "tenant to allowlist", "summary": "request" } ] } } }, "description": "tenant to allowlist", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_db.AllowedAzureTenant" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid body, tenant_id not a UUID, or default group invalid / admin-tier" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "super-admin token required" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "a tenant with this tenant_id already exists" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Add an Azure AD tenant", "tags": [ "Admin: shared infrastructure" ] } }, "/api/v1/admin/azure-tenants/{id}": { "delete": { "description": "Removes an Azure AD tenant from the allowlist and, as a security side effect, bans every user authenticated through that tenant and revokes their refresh tokens. Super-admin token only; the deletion (with banned/revoked counts) is audit-logged.", "parameters": [ { "description": "Azure tenant allowlist entry ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIMessage" } } }, "description": "azure tenant deleted" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "super-admin token required" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "azure tenant not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Delete an Azure AD tenant", "tags": [ "Admin: shared infrastructure" ] }, "get": { "description": "Returns one Azure AD tenant allowlist entry by its ID. Super-admin token only.", "parameters": [ { "description": "Azure tenant allowlist entry ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_db.AllowedAzureTenant" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "super-admin token required" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "azure tenant not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Get an Azure AD tenant", "tags": [ "Admin: shared infrastructure" ] }, "put": { "description": "Updates an Azure AD tenant allowlist entry; omitted fields are left unchanged and an empty default_org_id/default_group_id clears it. Same validation as create: tenant_id must be a UUID, and a default group must belong to the default org and not be an admin-tier group. Super-admin token only; the change is audit-logged.", "parameters": [ { "description": "Azure tenant allowlist entry ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.azureTenantUpdateRequest", "description": "fields to update", "summary": "request" } ] } } }, "description": "fields to update", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_db.AllowedAzureTenant" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid body, tenant_id not a UUID, or default group invalid / admin-tier" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "super-admin token required" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "azure tenant not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "a tenant with this tenant_id already exists" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Update an Azure AD tenant", "tags": [ "Admin: shared infrastructure" ] } }, "/api/v1/admin/cache/stats": { "get": { "description": "Returns statistics for the RBAC permission cache (entry count, expired-pending count, capacity) — cluster-wide observability tooling. Because these counts expose cross-org cardinality, the endpoint is restricted to the super-admin (full X-Admin-Token); tier-2 org-admin JWTs and the operator token are rejected with 403.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.CacheStats" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, or caller is not a super-admin" } }, "security": [ { "AdminToken": [] } ], "summary": "Get RBAC cache stats", "tags": [ "Admin: RBAC" ] } }, "/api/v1/admin/compliance/currency": { "get": { "description": "Returns the fleet-wide default (base) currency, the full list of supported fiat currencies, and whether CoinGecko price polling is enabled. This is the platform-wide fallback; each org can override it with its own per-org currency (RD-1158). Read-only; any admin token.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.ComplianceBaseCurrencyResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Get the global base currency", "tags": [ "Admin: compliance" ] }, "put": { "description": "Switches the fleet-wide base currency and re-values the cached system and manual token prices from their stored multi-currency prices. Super-admin only — it is a platform-wide setting affecting every tenant. If manual token prices are missing for the target currency, the switch is refused with 409 and the affected tokens unless force=true is set (those tokens then block transfers until priced). The change is written to the RBAC audit log.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.ComplianceSetBaseCurrencyRequest", "description": "target currency and force flag", "summary": "request" } ] } } }, "description": "target currency and force flag", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.ComplianceSetBaseCurrencyResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid body or unsupported currency" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, or super-admin token required" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.ComplianceCurrencyConflictResponse" } } }, "description": "manual token prices missing for the target currency; set force=true" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Set the global base currency", "tags": [ "Admin: compliance" ] } }, "/api/v1/admin/compliance/sanctions": { "get": { "description": "Returns blocklisted addresses (global or per-org), paginated. Scope is enforced by caller type: super-admin sees any scope; a tier-2 org-admin JWT must pass an in-scope org_id (global rows are super-admin only); the operator token may read the global list but not a specific org's blocklist.", "parameters": [ { "description": "Restrict to one org's blocklist (required for tier-2 org-admin JWTs; omit for the global list)", "in": "query", "name": "org_id", "schema": { "type": "string" } }, { "description": "Max rows to return (default 50, capped at 1000)", "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "description": "Rows to skip (default 0)", "in": "query", "name": "offset", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": { "items": {}, "type": "array", "uniqueItems": false }, "limit": { "example": 50, "type": "integer" }, "offset": { "example": 0, "type": "integer" }, "total": { "example": 42, "type": "integer" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "org_id query parameter is required (tier-2 org-admin JWT)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, org out of scope, or a per-org read attempted with the operator token" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "List sanctioned addresses", "tags": [ "Admin: compliance" ] }, "post": { "description": "Adds an address to the compliance blocklist. Omit org_id for a GLOBAL sanction (super-admin only); set it for a per-org sanction (the org admin's job — the operator/super-admin token cannot add per-org rows). Tier-2 org-admin JWTs must scope to an org they fully administer. The address is normalized to lowercase and the action is written to the RBAC audit log.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.ComplianceSanctionAddRequest", "description": "sanction fields", "summary": "request" } ] } } }, "description": "sanction fields", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_compliance.SanctionedAddress" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid body, address, or reason too long" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, global requires super-admin, or per-org must be in scope and is not addable with the operator token" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Add a sanctioned address", "tags": [ "Admin: compliance" ] } }, "/api/v1/admin/compliance/sanctions/{id}": { "delete": { "description": "Removes a sanction from the blocklist by ID. Removing a global row requires super-admin; removing a per-org row is the org admin's job (in scope) and is not permitted with the operator/super-admin token. To avoid a cross-org existence oracle, an unknown ID and an out-of-scope row both return the same opaque 403. The action is written to the RBAC audit log.", "parameters": [ { "description": "Sanction row ID (UUID)", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIMessage" } } }, "description": "sanctioned address removed" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, row not found, out of scope, global requires super-admin, or per-org not removable with the operator token" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Remove a sanctioned address", "tags": [ "Admin: compliance" ] } }, "/api/v1/admin/compliance/system-token-prices": { "get": { "description": "Returns the fleet-wide system token price cache (populated by the CoinGecko poller) plus the active global base currency. Each entry carries an is_stale flag when its last update is older than the configured staleness threshold. Read-only; any admin token.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.ComplianceSystemTokenPriceListResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "List system token prices", "tags": [ "Admin: compliance" ] } }, "/api/v1/admin/contracts/by-address/{address}": { "get": { "description": "Resolves a contract by address across all organizations, for the claim-unregistered-contract flow. The super-admin and a JWT admin of the owning org receive the full contract, organization, and grant topology; a JWT admin outside the owning org's scope receives only {address, registered} (audit H2). Not readable with the restricted operator token.", "parameters": [ { "description": "Contract address (0x-prefixed hex)", "in": "path", "name": "address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.contractLookupFullResponse" } } }, "description": "full payload for super-admin / owning-org admin; out-of-scope JWT admins receive contractLookupMinimalResponse instead" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "operator token cannot read tenant data" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "contract not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Look up a contract by address (cross-org)", "tags": [ "Admin: RBAC" ] } }, "/api/v1/admin/dev/deploy-demo-erc20": { "post": { "description": "Deploys a DemoToken (DEMO) ERC-20 contract via the configured node and returns its address and transaction hash. Self-gated to non-production builds: returns 403 when running in production. Optionally registers the deployed contract to an organization (and grants it to the deployer's group) when org_id is supplied. Requires an admin token and a private-network source address.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.DeployDemoERC20Request", "description": "optional org to register the contract to, and contract name", "summary": "request" } ] } } }, "description": "optional org to register the contract to, and contract name" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.DeployDemoERC20Response" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid request body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "not available in production, or source address not on the private network" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "organization not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "deployment failed" } }, "security": [ { "AdminToken": [] } ], "summary": "Deploy a demo ERC-20 token (dev only)", "tags": [ "Admin: ops" ] } }, "/api/v1/admin/disclosure/check-access": { "get": { "description": "Reports whether the requester DID currently holds an active, non-expired disclosure grant over the target user's data. Used by the block explorer to authorize a viewer. Fail-closed: when no active grant exists the response is 200 with has_access=false (not an error), and when a grant exists the response includes the grant ID, scope, disclosure level, and expiry so the caller can enforce it.", "parameters": [ { "description": "DID of the viewer whose access is being checked", "in": "query", "name": "requester_did", "required": true, "schema": { "type": "string" } }, { "description": "DID of the user whose data would be viewed", "in": "query", "name": "target_user_did", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.DisclosureCheckAccessResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "requester_did and target_user_did are required" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Check disclosure access for a DID pair", "tags": [ "Admin: disclosure" ] } }, "/api/v1/admin/disclosure/grants": { "get": { "description": "Lists disclosure grants (approved requests with an access token), filtered and clamped to the caller's org scope so a caller only sees grants for orgs they administer. When org_id is omitted it falls back to the caller's single admin org (super-admin/dev defaults to the system org); a multi-org JWT admin must supply org_id. Grant token hashes are never included in the response.", "parameters": [ { "description": "Organization to list grants for; required for multi-org JWT admins", "in": "query", "name": "org_id", "schema": { "type": "string" } }, { "description": "Filter by grant status", "in": "query", "name": "status", "schema": { "enum": [ "approved", "revoked", "expired" ], "type": "string" } }, { "description": "Filter by the user whose data is targeted", "in": "query", "name": "target_user_id", "schema": { "type": "string" } }, { "description": "Filter by the requester DID", "in": "query", "name": "requester_did", "schema": { "type": "string" } }, { "description": "Filter by disclosure level", "in": "query", "name": "disclosure_level", "schema": { "enum": [ "full", "pseudonymous", "redacted" ], "type": "string" } }, { "description": "Only grants created on or after this RFC3339 timestamp", "in": "query", "name": "date_from", "schema": { "type": "string" } }, { "description": "Only grants created on or before this RFC3339 timestamp", "in": "query", "name": "date_to", "schema": { "type": "string" } }, { "description": "Maximum number of results", "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "description": "Number of results to skip", "in": "query", "name": "offset", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_disclosure.GrantListResult" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "org_id required (ambiguous multi-org caller)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, or org_id outside the caller's scope" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "List disclosure grants", "tags": [ "Admin: disclosure" ] } }, "/api/v1/admin/disclosure/grants/{grant_id}/events": { "get": { "description": "Returns the disclosure access audit trail for a grant — each event records when the grant's data was viewed, by whom, and what resource was accessed. Requires a valid grant token (X-Disclosure-Token header or token query parameter) that must belong to the grant named in the path — a token for a different grant is rejected (403).", "parameters": [ { "description": "Disclosure grant ID", "in": "path", "name": "grant_id", "required": true, "schema": { "type": "string" } }, { "description": "Grant access token (or pass as the token query parameter)", "in": "header", "name": "X-Disclosure-Token", "schema": { "type": "string" } }, { "description": "Grant access token (alternative to the X-Disclosure-Token header)", "in": "query", "name": "token", "schema": { "type": "string" } }, { "description": "Max rows to return (1-1000)", "in": "query", "name": "limit", "schema": { "default": 100, "type": "integer" } }, { "description": "Rows to skip (pagination)", "in": "query", "name": "offset", "schema": { "default": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_disclosure.Event" }, "type": "array" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token, or invalid/absent disclosure token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, or token does not match the grant" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Get access events for a grant", "tags": [ "Admin: disclosure" ] } }, "/api/v1/admin/disclosure/grants/{grant_id}/logs": { "get": { "description": "Returns the target user's RPC activity log entries authorized by a disclosure grant. Requires a valid grant token (X-Disclosure-Token header or token query parameter) that must belong to the grant named in the path — a token for a different grant is rejected (403). Results are bounded to the grant's scope and time window; each access is itself recorded as a disclosure event.", "parameters": [ { "description": "Disclosure grant ID", "in": "path", "name": "grant_id", "required": true, "schema": { "type": "string" } }, { "description": "Grant access token (or pass as the token query parameter)", "in": "header", "name": "X-Disclosure-Token", "schema": { "type": "string" } }, { "description": "Grant access token (alternative to the X-Disclosure-Token header)", "in": "query", "name": "token", "schema": { "type": "string" } }, { "description": "Max rows to return (1-1000)", "in": "query", "name": "limit", "schema": { "default": 100, "type": "integer" } }, { "description": "Rows to skip (pagination)", "in": "query", "name": "offset", "schema": { "default": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_disclosure.ActivityLogEntry" }, "type": "array" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token, or invalid/absent disclosure token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, or token does not match the grant" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Get activity logs for a grant", "tags": [ "Admin: disclosure" ] } }, "/api/v1/admin/disclosure/grants/{grant_id}/report/{report_type}": { "get": { "description": "Generates (or returns) a compliance report of the given type over the target user's activity authorized by a disclosure grant. Requires a valid grant token (X-Disclosure-Token header or token query parameter) that must belong to the grant named in the path — a token for a different grant is rejected (403). The report_type must be one of the supported values; the access is recorded as a disclosure event.", "parameters": [ { "description": "Disclosure grant ID", "in": "path", "name": "grant_id", "required": true, "schema": { "type": "string" } }, { "description": "Report type to generate", "in": "path", "name": "report_type", "required": true, "schema": { "enum": [ "activity_summary", "sanctions_check", "compliance_report" ], "type": "string" } }, { "description": "Grant access token (or pass as the token query parameter)", "in": "header", "name": "X-Disclosure-Token", "schema": { "type": "string" } }, { "description": "Grant access token (alternative to the X-Disclosure-Token header)", "in": "query", "name": "token", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_disclosure.Report" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid report type" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token, or invalid/absent disclosure token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, or token does not match the grant" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Generate a compliance report for a grant", "tags": [ "Admin: disclosure" ] } }, "/api/v1/admin/disclosure/grants/{grant_id}/revoke": { "post": { "description": "Revokes an active disclosure grant, immediately ending the authorized viewer's access. Only grants whose owning org the caller fully administers can be revoked; a grant outside the caller's scope, or one that does not exist, returns a generic 403 (no existence oracle). The request body is optional and carries only a free-text revocation reason.", "parameters": [ { "description": "Disclosure grant ID", "in": "path", "name": "grant_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.DisclosureReasonBody", "description": "optional revocation reason", "summary": "request" } ] } } }, "description": "optional revocation reason" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.DisclosureStatusResponse" } } }, "description": "status: revoked" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, or grant not found / outside the caller's scope" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Revoke a disclosure grant (admin)", "tags": [ "Admin: disclosure" ] } }, "/api/v1/admin/disclosure/grants/{grant_id}/summary": { "get": { "description": "Returns aggregated activity statistics (request counts, per-method breakdown, date range) for the target user's activity authorized by a disclosure grant. Requires a valid grant token (X-Disclosure-Token header or token query parameter) that must belong to the grant named in the path — a token for a different grant is rejected (403). The access is recorded as a disclosure event.", "parameters": [ { "description": "Disclosure grant ID", "in": "path", "name": "grant_id", "required": true, "schema": { "type": "string" } }, { "description": "Grant access token (or pass as the token query parameter)", "in": "header", "name": "X-Disclosure-Token", "schema": { "type": "string" } }, { "description": "Grant access token (alternative to the X-Disclosure-Token header)", "in": "query", "name": "token", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_disclosure.ActivitySummary" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token, or invalid/absent disclosure token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, or token does not match the grant" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Get activity summary for a grant", "tags": [ "Admin: disclosure" ] } }, "/api/v1/admin/disclosure/requests": { "get": { "description": "Lists disclosure requests, filtered and clamped to the caller's org scope: the org_id filter must be within the caller's admin scope, so a caller only ever sees requests for orgs they administer. When org_id is omitted it falls back to the caller's single admin org (super-admin/dev defaults to the system org); a multi-org JWT admin must supply org_id. Additional filters narrow the result set.", "parameters": [ { "description": "Organization to list requests for; required for multi-org JWT admins", "in": "query", "name": "org_id", "schema": { "type": "string" } }, { "description": "Filter by request status", "in": "query", "name": "status", "schema": { "enum": [ "pending", "approved", "rejected", "expired", "revoked" ], "type": "string" } }, { "description": "Filter by the user whose data is targeted", "in": "query", "name": "target_user_id", "schema": { "type": "string" } }, { "description": "Filter by the requester DID", "in": "query", "name": "requester_did", "schema": { "type": "string" } }, { "description": "Filter by disclosure level", "in": "query", "name": "disclosure_level", "schema": { "enum": [ "full", "pseudonymous", "redacted" ], "type": "string" } }, { "description": "Only requests created on or after this RFC3339 timestamp", "in": "query", "name": "date_from", "schema": { "type": "string" } }, { "description": "Only requests created on or before this RFC3339 timestamp", "in": "query", "name": "date_to", "schema": { "type": "string" } }, { "description": "Maximum number of results", "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "description": "Number of results to skip", "in": "query", "name": "offset", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_disclosure.DisclosureListResult" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "org_id required (ambiguous multi-org caller)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, or org_id outside the caller's scope" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "List disclosure requests", "tags": [ "Admin: disclosure" ] }, "post": { "description": "Creates a disclosure request on behalf of an authorized viewer (e.g. a regulator) targeting one user's activity. Scoped to the caller's admin authority: org_id must be an org the caller fully administers and target_user_id must share an org with the caller — a request cannot be manufactured for another org's user. org_id may be omitted only when it is unambiguous (single-org JWT admin, or super-admin/dev which defaults to the system org); a multi-org JWT admin must supply it. The created request is pending until the target user approves or rejects it.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.CreateDisclosureRequestBody", "description": "disclosure request (target_user_id and reason required)", "summary": "request" } ] } } }, "description": "disclosure request (target_user_id and reason required)", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_disclosure.Request" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid body, or org_id required (ambiguous multi-org caller)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, or org_id / target_user_id outside the caller's scope" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Create a disclosure request", "tags": [ "Admin: disclosure" ] } }, "/api/v1/admin/disclosure/requests/{request_id}": { "delete": { "description": "Deletes a disclosure request that is still pending. Only requests in an org the caller fully administers can be deleted; a request outside the caller's scope, or one that does not exist, returns a generic 403 (no existence oracle). Only pending requests are deletable — an already-decided request returns 400.", "parameters": [ { "description": "Disclosure request ID", "in": "path", "name": "request_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.DisclosureStatusResponse" } } }, "description": "status: deleted" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "request is not pending" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, or request not found / outside the caller's scope" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Delete a pending disclosure request", "tags": [ "Admin: disclosure" ] }, "get": { "description": "Returns a single disclosure request with related details (requester/target DIDs, any active grant ID). Readable only when the request's org is within the caller's admin scope; a request outside the caller's scope, or one that does not exist, returns a generic 403 (no existence oracle).", "parameters": [ { "description": "Disclosure request ID", "in": "path", "name": "request_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_disclosure.RequestWithDetails" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, or request not found / outside the caller's scope" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Get a disclosure request", "tags": [ "Admin: disclosure" ] } }, "/api/v1/admin/eth-addresses/collisions": { "get": { "description": "Returns ETH addresses linked to more than one DID — potential key-sharing or key-compromise events to review. A super-admin (full X-Admin-Token) receives the cluster-wide list; a tier-2 org-admin JWT receives only collisions involving at least one user in its org scope, so it cannot read foreign-org DIDs or addresses.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.ethAddressCollisionsResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "List ETH address collisions", "tags": [ "Admin: RBAC" ] } }, "/api/v1/admin/logs": { "get": { "description": "Filtered, paginated access-log rows. Results are scoped to the caller's organization(s) for a tier-2 admin JWT; the super-admin token sees fleet-wide rows. status_code and outcome are mutually exclusive. total is -1 when the count query fails.", "parameters": [ { "description": "Filter by caller external ID (DID)", "in": "query", "name": "external_id", "schema": { "type": "string" } }, { "description": "Filter by JSON-RPC method", "in": "query", "name": "method", "schema": { "type": "string" } }, { "description": "Filter by correlation ID", "in": "query", "name": "correlation_id", "schema": { "type": "string" } }, { "description": "Exact HTTP status code (mutually exclusive with outcome)", "in": "query", "name": "status_code", "schema": { "type": "integer" } }, { "description": "Status class filter", "in": "query", "name": "outcome", "schema": { "enum": [ "success", "denied", "error", "all" ], "type": "string" } }, { "description": "Start of time range (RFC3339)", "in": "query", "name": "from", "schema": { "type": "string" } }, { "description": "End of time range (RFC3339)", "in": "query", "name": "to", "schema": { "type": "string" } }, { "description": "Max rows (default 100, capped server-side)", "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "description": "Row offset for pagination (default 0)", "in": "query", "name": "offset", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.AdminLogsResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid filter (e.g. status_code+outcome together, bad timestamp)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "List access logs", "tags": [ "Admin: ops" ] } }, "/api/v1/admin/orgs": { "get": { "description": "Returns a paginated list of organizations. Visibility is scoped to the caller: a super-admin (full X-Admin-Token) sees every org, while a tier-2 org-admin JWT sees only the orgs it administers. System orgs are hidden unless include_system=true. The operator token may list orgs (org metadata is not tenant-confidential).", "parameters": [ { "description": "Max rows to return (default 50)", "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "description": "Rows to skip for pagination (default 0)", "in": "query", "name": "offset", "schema": { "type": "integer" } }, { "description": "Include seeded is_system orgs (default false)", "in": "query", "name": "include_system", "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.orgListResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "List organizations", "tags": [ "Admin: RBAC" ] }, "post": { "description": "Creates a new organization (tenant). This is a platform-level lifecycle operation reserved for the super-admin (full X-Admin-Token) and the operator token; a tier-2 org-admin JWT is rejected with 403. The slug must be URL-safe and unique: ^[A-Za-z0-9][A-Za-z0-9_-]*$, \u003c=100 chars.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.orgCreateRequest", "description": "organization to create", "summary": "request" } ] } } }, "description": "organization to create", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.Organization" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid body or slug format" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, or caller is a tier-2 org-admin JWT (only super-admin/operator may create orgs)" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "an organization with this slug already exists" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Create an organization", "tags": [ "Admin: RBAC" ] } }, "/api/v1/admin/orgs/{org_id}": { "delete": { "description": "Deletes an organization and cascades to its groups, contracts, and grants. Platform-level lifecycle reserved for the super-admin (full X-Admin-Token) and the operator token; a tier-2 org-admin JWT is rejected with 403. The default organization and system orgs cannot be deleted.", "parameters": [ { "description": "Organization ID (UUID)", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIMessage" } } }, "description": "organization deleted" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "cannot delete the default organization" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, caller is a tier-2 org-admin JWT, or the org is a system org" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "organization not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Delete an organization", "tags": [ "Admin: RBAC" ] }, "get": { "description": "Returns a single organization by its ID. Org-scoping middleware restricts a tier-2 org-admin JWT to orgs it administers; a super-admin (X-Admin-Token) or operator token may read any org.", "parameters": [ { "description": "Organization ID (UUID)", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.Organization" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, or org outside the caller's scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "organization not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Get an organization", "tags": [ "Admin: RBAC" ] }, "put": { "description": "Updates the slug, name, and/or settings of an organization. All body fields are optional; only supplied fields change. is_system organizations are identity-immutable and rejected with 403. Org-scoping middleware limits a tier-2 org-admin JWT to orgs it administers.", "parameters": [ { "description": "Organization ID (UUID)", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.orgUpdateRequest", "description": "fields to update (all optional)", "summary": "request" } ] } } }, "description": "fields to update (all optional)", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.Organization" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid body or slug format" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, org outside the caller's scope, or the org is a system org" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "organization not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "an organization with this slug already exists" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Update an organization", "tags": [ "Admin: RBAC" ] } }, "/api/v1/admin/orgs/{org_id}/compliance/address-thresholds": { "get": { "description": "Returns the organization's per-address travel-rule threshold overrides (paginated). An override takes precedence over the org-level threshold for that address. Tenant-confidential: not readable with the operator token — use a tier-2 org-admin JWT.", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Max rows to return (default 50, capped at 1000)", "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "description": "Rows to skip (default 0)", "in": "query", "name": "offset", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": { "items": {}, "type": "array", "uniqueItems": false }, "limit": { "example": 50, "type": "integer" }, "offset": { "example": 0, "type": "integer" }, "total": { "example": 42, "type": "integer" } }, "type": "object" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, org outside the caller's scope, or operator token (tenant data not readable)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "List address threshold overrides", "tags": [ "Admin: compliance" ] } }, "/api/v1/admin/orgs/{org_id}/compliance/address-thresholds/{address}": { "delete": { "description": "Removes a per-address threshold override for the organization; the org-level threshold then applies to that address again. Per-org management is the org admin's job (RD-1107).", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Address (0x-prefixed hex) the override applies to", "in": "path", "name": "address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIMessage" } } }, "description": "address threshold override deleted" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, org outside the caller's scope (read-only admins cannot mutate), or operator token (per-org management is the org admin's job)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "address threshold override not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Delete an address threshold override", "tags": [ "Admin: compliance" ] }, "put": { "description": "Creates or updates a per-address travel-rule threshold override for the organization. The override replaces the org-level threshold when valuing transfers involving that address. Per-org management is the org admin's job (RD-1107).", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Address (0x-prefixed hex) the override applies to", "in": "path", "name": "address", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.ComplianceThresholdOverrideUpsertRequest", "description": "override fields", "summary": "request" } ] } } }, "description": "override fields", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_compliance.AddressThresholdOverride" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid address, body, negative threshold, or note too long" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, org outside the caller's scope (read-only admins cannot mutate), or operator token (per-org management is the org admin's job)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Set an address threshold override", "tags": [ "Admin: compliance" ] } }, "/api/v1/admin/orgs/{org_id}/compliance/config": { "get": { "description": "Returns the organization's travel-rule compliance settings (enabled flag, fiat threshold, per-org currency, unknown-price policy, and enforcement mode). If the org has no config row yet, a default (disabled, cluster-default enforcement mode) is returned. Tenant-confidential: not readable with the operator token — use a tier-2 org-admin JWT.", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_compliance.ComplianceConfig" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, org outside the caller's scope, or operator token (tenant data not readable)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Get an org's compliance configuration", "tags": [ "Admin: compliance" ] }, "put": { "description": "Creates or updates the organization's compliance settings (enabled flag, fiat threshold, per-org currency, unknown-price policy, enforce/monitor mode). A partial update — only the fields present in the body are changed. Per-org management is the org admin's job; the operator/super-admin token cannot mutate per-org config (RD-1107). RD-1158 made currency a per-org setting owned here (the global base currency stays super-admin only). The change is written to the RBAC audit log.", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.ComplianceConfigUpdateRequest", "description": "compliance config fields to change", "summary": "request" } ] } } }, "description": "compliance config fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_compliance.ComplianceConfig" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid body, negative threshold, or unsupported policy/mode/currency" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, org outside the caller's scope (read-only admins cannot mutate), or operator token (per-org management is the org admin's job)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Update an org's compliance configuration", "tags": [ "Admin: compliance" ] } }, "/api/v1/admin/orgs/{org_id}/compliance/logs": { "get": { "description": "Returns the organization's immutable compliance decision log (each allowed/denied transfer decision), paginated and filterable. Tenant-confidential: not readable with the operator token — use a tier-2 org-admin JWT.", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Max rows to return (default 50, capped at 1000)", "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "description": "Rows to skip (default 0)", "in": "query", "name": "offset", "schema": { "type": "integer" } }, { "description": "Filter by originating user (substring match)", "in": "query", "name": "user_search", "schema": { "type": "string" } }, { "description": "Filter by decision", "in": "query", "name": "decision", "schema": { "enum": [ "allowed", "denied" ], "type": "string" } }, { "description": "Filter by transfer type", "in": "query", "name": "transfer_type", "schema": { "enum": [ "eth", "erc20" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": { "items": {}, "type": "array", "uniqueItems": false }, "limit": { "example": 50, "type": "integer" }, "offset": { "example": 0, "type": "integer" }, "total": { "example": 42, "type": "integer" } }, "type": "object" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, org outside the caller's scope, or operator token (tenant data not readable)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "List compliance decision logs", "tags": [ "Admin: compliance" ] } }, "/api/v1/admin/orgs/{org_id}/compliance/tokens": { "get": { "description": "Returns the fiat token prices configured for the organization, used to value transfers for the travel-rule threshold. Tenant-confidential: not readable with the operator token — use a tier-2 org-admin JWT.", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": { "items": {}, "type": "array", "uniqueItems": false } }, "type": "object" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, org outside the caller's scope, or operator token (tenant data not readable)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "List an org's token prices", "tags": [ "Admin: compliance" ] } }, "/api/v1/admin/orgs/{org_id}/compliance/tokens/{token_address}": { "delete": { "description": "Removes the configured fiat price for a token in the organization. token_address is \"native\" or a 0x-prefixed contract address. Per-org management is the org admin's job (RD-1107).", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Token contract address (0x-prefixed) or 'native'", "in": "path", "name": "token_address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIMessage" } } }, "description": "token price deleted" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, org outside the caller's scope (read-only admins cannot mutate), or operator token (per-org management is the org admin's job)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "token price not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Delete a token price for an org", "tags": [ "Admin: compliance" ] }, "put": { "description": "Creates or updates the fiat price of a token for the organization. token_address is \"native\" (for the chain's native coin) or a 0x-prefixed contract address. Supply coingecko_id to source the price from the system cache, or a manual prices map keyed by currency code. Per-org management is the org admin's job (RD-1107). The change is written to the RBAC audit log.", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Token contract address (0x-prefixed) or 'native'", "in": "path", "name": "token_address", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.ComplianceTokenPriceUpsertRequest", "description": "token price fields", "summary": "request" } ] } } }, "description": "token price fields", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_compliance.TokenPrice" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid body, address, coingecko_id, currency, price, decimals, or symbol" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, org outside the caller's scope (read-only admins cannot mutate), or operator token (per-org management is the org admin's job)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Set a token price for an org", "tags": [ "Admin: compliance" ] } }, "/api/v1/admin/orgs/{org_id}/compliance/travel-rule-records": { "get": { "description": "Returns the organization's travel-rule records, most recent first, with pagination. Tenant-confidential: not readable with the operator token — use a tier-2 org-admin JWT.", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Max rows to return (default 50, capped at 1000)", "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "description": "Rows to skip (default 0)", "in": "query", "name": "offset", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": { "items": {}, "type": "array", "uniqueItems": false }, "limit": { "example": 50, "type": "integer" }, "offset": { "example": 0, "type": "integer" }, "total": { "example": 42, "type": "integer" } }, "type": "object" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, org outside the caller's scope, or operator token (tenant data not readable)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "List travel-rule records", "tags": [ "Admin: compliance" ] }, "post": { "description": "Creates an IVMS101 travel-rule record (originator/beneficiary data) that satisfies the compliance check for a subsequent transfer above the threshold. The fiat amount is computed server-side from amount_wei and the configured token price — it is never taken from the request. transfer_type is \"eth\" or \"erc20\" (token_address required for erc20); the originator must be a member of the org. The response includes an advisory warning when the amount is below the applicable threshold (the record may never be used). Per-org management is the org admin's job (RD-1107).", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.ComplianceTravelRuleRecordCreateRequest", "description": "travel-rule record fields", "summary": "request" } ] } } }, "description": "travel-rule record fields", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_compliance.TravelRuleRecord" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid body, amount, transfer_type, address, or no configured token price" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, org outside the caller's scope (read-only admins cannot mutate), or operator token (per-org management is the org admin's job)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Create a travel-rule record", "tags": [ "Admin: compliance" ] } }, "/api/v1/admin/orgs/{org_id}/compliance/travel-rule-records/{id}": { "delete": { "description": "Deletes a travel-rule record by ID. A record that has already been consumed by a transfer cannot be deleted (409). Per-org management is the org admin's job (RD-1107).", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Travel-rule record ID (UUID)", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "record deleted" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid record id format" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, org outside the caller's scope (read-only admins cannot mutate), or operator token (per-org management is the org admin's job)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "travel rule record not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "cannot delete a used travel rule record" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Delete a travel-rule record", "tags": [ "Admin: compliance" ] } }, "/api/v1/admin/orgs/{org_id}/contracts": { "get": { "description": "Lists the contracts registered to the organization, most recent first, with an optional case-insensitive search over name/address and a created-at date window. Scoped to {org_id}; a tier-2 admin only sees their own org's contracts.", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Max rows to return (default 50)", "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "description": "Rows to skip for pagination (default 0)", "in": "query", "name": "offset", "schema": { "type": "integer" } }, { "description": "Case-insensitive filter over contract name or address", "in": "query", "name": "search", "schema": { "type": "string" } }, { "description": "Only contracts created on or after this ISO 8601 date", "in": "query", "name": "created_after", "schema": { "type": "string" } }, { "description": "Only contracts created before this ISO 8601 date", "in": "query", "name": "created_before", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.contractListResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "operator token cannot read tenant data, or caller is out of org scope" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "List contracts", "tags": [ "Admin: RBAC" ] }, "post": { "description": "Registers a contract (address plus optional name and metadata) in the organization. The address is validated and stored lowercase. Scoped to {org_id}; the restricted operator token is rejected because per-org contract management is the org admin's job.", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.contractCreateRequest", "description": "contract to create", "summary": "request" } ] } } }, "description": "contract to create", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.Contract" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid body or invalid Ethereum address format" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "operator token cannot manage per-org contracts, or caller is out of org scope" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "a contract with this address already exists in the organization" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Create a contract", "tags": [ "Admin: RBAC" ] } }, "/api/v1/admin/orgs/{org_id}/contracts/batch-move": { "post": { "description": "Moves up to 200 contracts to an existing group or a newly created one (grant them to the target, drop their grants to auto-created source groups, optionally delete emptied source groups). All contracts must belong to the organization. Scoped to {org_id}; the restricted operator token is rejected.", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.contractBatchMoveRequest", "description": "move request (provide exactly one of target_group_id or new_group)", "summary": "request" } ] } } }, "description": "move request (provide exactly one of target_group_id or new_group)", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.contractBatchMoveResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid body, too many contract IDs, missing/ambiguous target, or a contract/group not in this org" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "operator token cannot manage per-org contracts, or caller is out of org scope" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Batch-move contracts to a group", "tags": [ "Admin: RBAC" ] } }, "/api/v1/admin/orgs/{org_id}/contracts/claim": { "post": { "description": "Registers an on-chain contract to the organization when the caller proves deployment: the deployment transaction's receipt must name the claimed address, and the deployer address must be linked to a member of the claiming org. Fail-closed: every verification failure (already registered, unknown tx, receipt mismatch, deployer not in org, no bytecode) returns the same opaque 400 \"contract registration failed\" so the endpoint cannot be used as an existence or ownership oracle.", "parameters": [ { "description": "organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.contractClaimRequest", "description": "claimed address and deployment tx hash", "summary": "request" } ] } } }, "description": "claimed address and deployment tx hash", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.contractClaimResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid input, or opaque verification failure" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Forbidden" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Claim an unregistered contract (proof of deployment)", "tags": [ "Admin: RBAC" ] } }, "/api/v1/admin/orgs/{org_id}/contracts/grant-summary": { "get": { "description": "Returns, keyed by contract ID, the grant count and assigned group names for each of the organization's contracts that has at least one grant. Scoped to {org_id}; a tier-2 admin can only read their own org.", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.ContractGrantSummary" }, "type": "object" } } }, "description": "grant summary keyed by contract ID" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "operator token cannot read tenant data, or caller is out of org scope" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Get contract grant summary", "tags": [ "Admin: RBAC" ] } }, "/api/v1/admin/orgs/{org_id}/contracts/sync-check": { "post": { "description": "Runs eth_getCode for every registered contract in the organization and buckets them as existing, missing, or errored (RPC failure). Read-only reconciliation helper. Scoped to {org_id}.", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.contractSyncCheckResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "caller is out of org scope" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Check contracts against the chain", "tags": [ "Admin: RBAC" ] } }, "/api/v1/admin/orgs/{org_id}/contracts/sync-delete": { "post": { "description": "Deletes the given contracts only after re-verifying each still belongs to the organization and is still absent on-chain; contracts that now exist, belong elsewhere, or error are skipped with a reason. Scoped to {org_id}; the restricted operator token is rejected.", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.contractSyncDeleteRequest", "description": "contract IDs to delete", "summary": "request" } ] } } }, "description": "contract IDs to delete", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.contractSyncDeleteResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid body, or no contract IDs provided" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "operator token cannot manage per-org contracts, or caller is out of org scope" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Delete stale (missing) contracts", "tags": [ "Admin: RBAC" ] } }, "/api/v1/admin/orgs/{org_id}/contracts/{address}": { "delete": { "description": "Deletes a contract from the organization and invalidates the org's permission cache (its grants may affect many groups). Scoped to {org_id}; the restricted operator token is rejected.", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Contract address (0x-prefixed hex)", "in": "path", "name": "address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIMessage" } } }, "description": "contract deleted" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "operator token cannot manage per-org contracts, or caller is out of org scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "contract not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Delete a contract", "tags": [ "Admin: RBAC" ] }, "get": { "description": "Returns one contract by its address within the organization. Scoped to {org_id}; a tier-2 admin can only read their own org's contracts.", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Contract address (0x-prefixed hex)", "in": "path", "name": "address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.Contract" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "operator token cannot read tenant data, or caller is out of org scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "contract not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Get a contract", "tags": [ "Admin: RBAC" ] }, "put": { "description": "Updates the name and/or metadata of a contract; omitted fields are left unchanged. Scoped to {org_id}; the restricted operator token is rejected.", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Contract address (0x-prefixed hex)", "in": "path", "name": "address", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.contractUpdateRequest", "description": "fields to update", "summary": "request" } ] } } }, "description": "fields to update", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.Contract" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid request body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "operator token cannot manage per-org contracts, or caller is out of org scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "contract not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Update a contract", "tags": [ "Admin: RBAC" ] } }, "/api/v1/admin/orgs/{org_id}/contracts/{address}/abi": { "put": { "description": "Stores the contract's ABI (used for function-level access control and event redaction). The ABI must be a valid JSON array. Scoped to {org_id}; the restricted operator token is rejected.", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Contract address (0x-prefixed hex)", "in": "path", "name": "address", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.contractABIUpdateRequest", "description": "ABI JSON array", "summary": "request" } ] } } }, "description": "ABI JSON array", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.Contract" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid body, or ABI is not a valid JSON array" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "operator token cannot manage per-org contracts, or caller is out of org scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "contract not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Set a contract's ABI", "tags": [ "Admin: RBAC" ] } }, "/api/v1/admin/orgs/{org_id}/contracts/{address}/events": { "get": { "description": "Parses the contract's resolved ABI and returns its events with topic0 hashes and parameter info, for building event-rule configurations. Returns an empty list with a message when no ABI is registered. Scoped to {org_id}; a tier-2 admin can only read their own org's contracts.", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Contract address (0x-prefixed hex)", "in": "path", "name": "address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.contractEventsResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "the stored ABI could not be parsed" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "operator token cannot read tenant data, or caller is out of org scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "contract not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "List a contract's events", "tags": [ "Admin: RBAC" ] } }, "/api/v1/admin/orgs/{org_id}/contracts/{address}/events-allow-dynamic-payload": { "put": { "description": "Enables or disables the M15 opt-out that lets events with dynamic non-indexed payloads pass through to non-Full viewers without scanning for embedded foreign-org addresses. Default false (close-by-default). Super-admin token only — tier-2/3 org admins cannot flip it; the change is audit-logged with before/after state.", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Contract address (0x-prefixed hex)", "in": "path", "name": "address", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.contractEventsAllowDynamicPayloadRequest", "description": "flag value", "summary": "request" } ] } } }, "description": "flag value", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.Contract" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid address, invalid body, or events_allow_dynamic_payload is missing" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "super-admin token required" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "contract not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Toggle a contract's dynamic-payload event flag", "tags": [ "Admin: RBAC" ] } }, "/api/v1/admin/orgs/{org_id}/contracts/{address}/grants": { "get": { "description": "Lists the group grants attached to a contract (each links a group to the contract with optional function and event-rule restrictions). Scoped to {org_id}; a tier-2 admin can only read their own org's contracts.", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Contract address (0x-prefixed hex)", "in": "path", "name": "address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.ContractGrant" }, "type": "array" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "operator token cannot read tenant data, or caller is out of org scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "contract not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "List contract grants", "tags": [ "Admin: RBAC" ] }, "post": { "description": "Grants a group access to the contract, optionally restricting functions and event visibility. Non-deny event_rules require a resolvable ABI, and any custom hex address in an address-typed param rule must belong to this organization (cross-org references are rejected). Scoped to {org_id}; the restricted operator token is rejected.", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Contract address (0x-prefixed hex)", "in": "path", "name": "address", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.contractGrantCreateRequest", "description": "grant to create", "summary": "request" } ] } } }, "description": "grant to create", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.ContractGrant" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid body, invalid event rules, or event_rules set without a resolvable ABI" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "operator token cannot manage per-org grants, caller is out of org scope, or a param rule references a cross-org / unregistered address" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "contract not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Create a contract grant", "tags": [ "Admin: RBAC" ] } }, "/api/v1/admin/orgs/{org_id}/contracts/{address}/grants/{group_id}": { "delete": { "description": "Removes a group's grant on the contract and invalidates that group's permission cache. Scoped to {org_id}; the restricted operator token is rejected.", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Contract address (0x-prefixed hex)", "in": "path", "name": "address", "required": true, "schema": { "type": "string" } }, { "description": "Group ID the grant belongs to", "in": "path", "name": "group_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIMessage" } } }, "description": "grant deleted" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "operator token cannot manage per-org grants, or caller is out of org scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "contract or grant not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Delete a contract grant", "tags": [ "Admin: RBAC" ] }, "put": { "description": "Updates a grant's function and/or event rules. An absent key means no change; an explicit null clears it; event_rules also accepts \"*\" (all events). Non-deny event_rules require a resolvable ABI, and custom hex address param rules must stay within this organization. Scoped to {org_id}; the restricted operator token is rejected.", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Contract address (0x-prefixed hex)", "in": "path", "name": "address", "required": true, "schema": { "type": "string" } }, { "description": "Group ID the grant belongs to", "in": "path", "name": "group_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.contractGrantUpdateRequest", "description": "fields to update", "summary": "request" } ] } } }, "description": "fields to update", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.ContractGrant" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid body, invalid functions/event_rules, or event_rules set without a resolvable ABI" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "operator token cannot manage per-org grants, caller is out of org scope, or a param rule references a cross-org / unregistered address" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "contract or grant not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Update a contract grant", "tags": [ "Admin: RBAC" ] } }, "/api/v1/admin/orgs/{org_id}/contracts/{address}/visibleto-unlock": { "put": { "description": "Enables or disables the RD-874 per-contract opt-in that lets a tx sender grant per-event visibility to DIDs listed in the transaction's visibleTo. Enabling it widens who can see events on this contract, so review grants first. Scoped to {org_id}; the restricted operator token is rejected.", "parameters": [ { "description": "Organization ID", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Contract address (0x-prefixed hex)", "in": "path", "name": "address", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.contractVisibleToUnlockRequest", "description": "flag value", "summary": "request" } ] } } }, "description": "flag value", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.Contract" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid body, or allow_visibleto_unlock is missing" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "operator token cannot manage per-org contracts, or caller is out of org scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "contract not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Toggle a contract's visibleTo-unlock flag", "tags": [ "Admin: RBAC" ] } }, "/api/v1/admin/orgs/{org_id}/dry-run": { "post": { "description": "Evaluates \"what would this user see if they made this RPC call?\" in the path org, without mutating chain state. Read methods are forwarded and redacted as the impersonated user; write methods (eth_sendTransaction / eth_sendRawTransaction) are translated to debug_traceCall so the RBAC verdict and the events the tx would emit (and the subset visible to the user) can be inspected. Requires a tier-2 org-admin JWT of the path org: X-Admin-Token credentials (both the full super-admin token and the operator token) are explicitly rejected, since impersonation reads tenant data as the user. The impersonated user must exist and be a member of the path org, else an opaque 404 (no cross-org existence leak). Every evaluation is written to the impersonation audit log fail-closed. Supported methods: eth_call, eth_getLogs, eth_getTransactionReceipt, eth_getTransactionByHash, eth_getBalance, eth_getCode, eth_getStorageAt, eth_blockNumber, eth_chainId, eth_sendTransaction, eth_sendRawTransaction.", "parameters": [ { "description": "Organization ID (UUID)", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.dryRunRequest", "description": "impersonation request (user_did and rpc.method/params)", "summary": "request" } ] } } }, "description": "impersonation request (user_did and rpc.method/params)", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.dryRunResponseDoc" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid body, unsupported method, self-dry-run, or missing user_did/rpc.method" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing admin authentication (no admin_subject)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, or X-Admin-Token/operator credentials used (dry-run requires a tier-2 admin JWT)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "impersonated user not found or not a member of the path org (opaque)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "internal error (includes audit-log write failure — response withheld)" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "upstream node error or trace failure" } }, "security": [ { "AdminToken": [] } ], "summary": "Dry-run an RPC call as a user", "tags": [ "Admin: RBAC" ] } }, "/api/v1/admin/orgs/{org_id}/groups": { "get": { "description": "Returns a paginated list of the organization's groups, each with its access settings (RPC method allowlist, claims, rate limits); rpc_api_key values are masked. Optional case-insensitive search filter. Tenant-confidential: rejected for the operator token (403); use a tier-2 org-admin JWT. Org-scoping middleware limits a tier-2 JWT to orgs it administers.", "parameters": [ { "description": "Organization ID (UUID)", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Case-insensitive filter on group name/slug", "in": "query", "name": "search", "schema": { "type": "string" } }, { "description": "Max rows to return (default 50)", "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "description": "Rows to skip for pagination (default 0)", "in": "query", "name": "offset", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.groupListResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, org outside the caller's scope, or operator token (tenant data not readable)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "List groups", "tags": [ "Admin: RBAC" ] }, "post": { "description": "Creates a group within the organization. Body: slug (required, URL-safe, unique per org), name (required), description, is_org_admin, is_org_readonly_admin. Admin-tier flags carry escalation gates: a tier-2 org-admin JWT cannot create an is_org_admin group (super-admin only); the operator token cannot create a regular group (org admin's job). is_org_admin and is_org_readonly_admin are mutually exclusive.", "parameters": [ { "description": "Organization ID (UUID)", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.groupCreateRequest", "description": "group to create", "summary": "request" } ] } } }, "description": "group to create", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.Group" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid body, slug format, or mutually-exclusive admin roles" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, org outside the caller's scope, tier-2 JWT minting an org-admin group, or operator token creating a regular group" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "a group with this slug or name already exists in the organization" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Create a group", "tags": [ "Admin: RBAC" ] } }, "/api/v1/admin/orgs/{org_id}/groups/batch-delete": { "post": { "description": "Deletes multiple groups (and their dependencies) in a single atomic transaction; if any group fails a check the whole batch rolls back. Body: group_ids ([]string, required, max 200). Every group must belong to the path org. A tier-2 org-admin JWT batch that includes any is_org_admin group is rejected (super-admin only); the operator token is rejected if the batch includes any regular group.", "parameters": [ { "description": "Organization ID (UUID)", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.groupBatchDeleteRequest", "description": "group IDs to delete", "summary": "request" } ] } } }, "description": "group IDs to delete", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.groupBatchDeleteResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid body, empty group_ids, more than 200 IDs, or one or more groups not in the organization" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, org outside the caller's scope, tier-2 JWT batch including an org-admin group, or operator token batch including a regular group" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Batch-delete groups", "tags": [ "Admin: RBAC" ] } }, "/api/v1/admin/orgs/{org_id}/groups/batch-delete-preview": { "post": { "description": "Returns, for each requested group, its member count and the contract addresses a deletion would cascade — a dry run for the batch-delete endpoint. Body: group_ids ([]string, required, max 200). Every group must belong to the path org; a foreign or unknown ID returns an opaque 403.", "parameters": [ { "description": "Organization ID (UUID)", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.groupBatchDeleteRequest", "description": "group IDs to preview", "summary": "request" } ] } } }, "description": "group IDs to preview", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.groupBatchDeletePreviewResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid body, empty group_ids, or more than 200 IDs" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, org outside the caller's scope, or a group not in the path org (opaque)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Preview a batch group deletion", "tags": [ "Admin: RBAC" ] } }, "/api/v1/admin/orgs/{org_id}/groups/{group_id}": { "delete": { "description": "Deletes a group. The group must belong to the path org (opaque 403 otherwise). is_system groups cannot be deleted. A tier-2 org-admin JWT cannot delete an is_org_admin group (super-admin only); the operator token cannot delete a regular group.", "parameters": [ { "description": "Organization ID (UUID)", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Group ID (UUID)", "in": "path", "name": "group_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIMessage" } } }, "description": "group deleted" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, group not in the path org, system group, tier-2 JWT deleting an org-admin group, or operator token deleting a regular group" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Delete a group", "tags": [ "Admin: RBAC" ] }, "get": { "description": "Returns a single group. The group must belong to the org in the path (verified server-side); a mismatch returns an opaque 403 identical to the not-found case so foreign-org group IDs cannot be probed. Tenant-confidential: rejected for the operator token (403).", "parameters": [ { "description": "Organization ID (UUID)", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Group ID (UUID)", "in": "path", "name": "group_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.Group" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, group not in the path org (opaque), or operator token (tenant data not readable)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Get a group", "tags": [ "Admin: RBAC" ] }, "put": { "description": "Updates a group's name, description, is_org_admin, and/or is_org_readonly_admin. All body fields are optional. is_system groups are identity-immutable (403). Escalation gates apply: a tier-2 org-admin JWT cannot change is_org_admin in either direction (super-admin only); the operator token cannot edit a regular group unless the update promotes it to an admin-tier group. The resulting state cannot be both full and read-only org admin.", "parameters": [ { "description": "Organization ID (UUID)", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Group ID (UUID)", "in": "path", "name": "group_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.groupUpdateRequest", "description": "fields to update (all optional)", "summary": "request" } ] } } }, "description": "fields to update (all optional)", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.Group" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid body or mutually-exclusive admin roles" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, group not in the path org, system group, tier-2 JWT changing is_org_admin, or operator token editing a regular group" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "a group with this slug or name already exists in the organization" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Update a group", "tags": [ "Admin: RBAC" ] } }, "/api/v1/admin/orgs/{org_id}/groups/{group_id}/access": { "get": { "description": "Returns the group's access settings: the RPC method allowlist, operational claims, and rate limits. For child groups, effective (parent-narrowed) claims are computed. Any rpc_api_key is masked. Returns an empty access object if none is configured. The group must belong to the path org (opaque 403 otherwise). Tenant-confidential: rejected for the operator token (403).", "parameters": [ { "description": "Organization ID (UUID)", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Group ID (UUID)", "in": "path", "name": "group_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.GroupAccess" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, group not in the path org, or operator token (tenant data not readable)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Get group access", "tags": [ "Admin: RBAC" ] }, "put": { "description": "Creates or replaces the group's access settings. Body: allowed_methods ([]string; \"*\" expands to the full method list), claims ([]string of operational claims: deploy/upgrade/admin), rpc_api_key (encrypted at rest, never returned in clear), verbose_errors. is_system group access is super-admin-only (X-Admin-Token). Reshaping an is_org_admin group's access is super-admin-only; reshaping a regular group's access is rejected for the operator token. On is_org_admin groups claims must be empty and at least one method is required. The returned rpc_api_key is masked.", "parameters": [ { "description": "Organization ID (UUID)", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } }, { "description": "Group ID (UUID)", "in": "path", "name": "group_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.groupAccessRequest", "description": "access settings", "summary": "request" } ] } } }, "description": "access settings", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.GroupAccess" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid body, method/claim mismatch, or org-admin claim/method invariant violated" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, group not in the path org, system-group access changed by non-super-admin, tier-2 JWT reshaping an org-admin group, or operator token reshaping a regular group" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Set group access", "tags": [ "Admin: RBAC" ] } }, "/api/v1/admin/orgs/{org_id}/memberships/by-did": { "delete": { "description": "Removes a user identified by DID from a group in the path org (the symmetric counterpart of onboard-by-did). Body: did (required), group_id (required). Requires full (is_org_admin) scope over the path org; the target group must belong to that org (opaque 403 otherwise). Removing from an is_org_admin group is super-admin-only; a regular group is rejected for the operator token. A DID that is unknown, or has no membership in the target group, returns the SAME opaque 403 as a foreign-org group — no existence oracle. No tenant read is performed.", "parameters": [ { "description": "Organization ID (UUID)", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.membershipByDIDRemovalRequest", "description": "removal request", "summary": "request" } ] } } }, "description": "removal request", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIMessage" } } }, "description": "membership deleted" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, path org outside the caller's full-admin scope, target group not in the path org / DID not found / no membership (all opaque), tier-2 JWT removing from an org-admin group, or operator token removing from a regular group" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Remove a DID from a group", "tags": [ "Admin: RBAC" ] }, "post": { "description": "Onboards a user identified by DID directly into a group in the path org, auto-provisioning the user if the DID is not yet known. Body: did (required, a syntactically valid W3C DID; iden3/Polygon-ID DIDs are checksum-verified), group_id (required), expires_at (optional RFC3339, future). Requires full (is_org_admin) scope over the path org; the target group must belong to that org (opaque 403 otherwise). Onboarding into an is_org_admin group is super-admin-only; a regular group is rejected for the operator token. Ban state is never revealed via this endpoint. ADD semantics — a new user is not also placed in the default group.", "parameters": [ { "description": "Organization ID (UUID)", "in": "path", "name": "org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.membershipByDIDRequest", "description": "onboarding request", "summary": "request" } ] } } }, "description": "onboarding request", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.membershipByDIDResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid body, invalid DID, or expires_at (must be RFC3339 and in the future)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, path org outside the caller's full-admin scope, target group not in the path org (opaque), tier-2 JWT onboarding into an org-admin group, or operator token onboarding into a regular group" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "user is already a member of this group" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Onboard a DID into a group", "tags": [ "Admin: RBAC" ] } }, "/api/v1/admin/sessions": { "get": { "description": "Returns the in-flight authentication sessions (id, created/expiry/completed timestamps) held in the session store. These are cluster-wide auth-flow sessions, not org-tagged, so the endpoint is restricted to the super-admin (full X-Admin-Token); tier-2 org-admin JWTs and the operator token are rejected with 403.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.SessionListResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, caller is not a super-admin, or operator token (tenant data not readable)" } }, "security": [ { "AdminToken": [] } ], "summary": "List auth sessions", "tags": [ "Admin: RBAC" ] } }, "/api/v1/admin/sessions/{session_id}": { "delete": { "description": "Terminates a single in-flight authentication session by ID. Restricted to the super-admin (full X-Admin-Token) — sessions are cluster-wide, so allowing tier-2 org-admin JWTs would enable mass-DoS of in-progress logins; the operator token is likewise rejected.", "parameters": [ { "description": "Auth session ID", "in": "path", "name": "session_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIMessage" } } }, "description": "session deleted" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, or caller is not a super-admin" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "session not found or expired" } }, "security": [ { "AdminToken": [] } ], "summary": "Delete an auth session", "tags": [ "Admin: RBAC" ] } }, "/api/v1/admin/shared-infrastructure": { "get": { "description": "Lists the global shared-infrastructure contracts the cross-org trace validator skips (public routers, factories, resolvers). Super-admin token only — the list reveals the operator's trust topology, so org admins cannot read it.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.sharedInfraListResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "super-admin token required" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "List shared infrastructure", "tags": [ "Admin: shared infrastructure" ] }, "post": { "description": "Registers a global shared-infrastructure contract (address from the body). The optional codehash pin, if supplied, must be a 0x-prefixed 32-byte hex string; omit it and use refresh-codehash to compute it server-side. Super-admin token only; the mutation is audit-logged.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.sharedInfraInput", "description": "shared-infrastructure entry to create", "summary": "request" } ] } } }, "description": "shared-infrastructure entry to create", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.SharedInfrastructure" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid body, invalid address, invalid codehash, or missing name" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "super-admin token required" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "address already registered; use PUT to update" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Add a shared-infrastructure entry", "tags": [ "Admin: shared infrastructure" ] } }, "/api/v1/admin/shared-infrastructure/{address}": { "delete": { "description": "Removes a contract from the global shared-infrastructure allowlist; the trace validator will resume enforcing cross-org checks on it. Super-admin token only; the deletion is audit-logged.", "parameters": [ { "description": "Contract address (0x-prefixed hex)", "in": "path", "name": "address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIMessage" } } }, "description": "shared_infrastructure entry deleted" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid address" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "super-admin token required" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Delete a shared-infrastructure entry", "tags": [ "Admin: shared infrastructure" ] }, "get": { "description": "Returns one global shared-infrastructure entry by address. Super-admin token only.", "parameters": [ { "description": "Contract address (0x-prefixed hex)", "in": "path", "name": "address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.SharedInfrastructure" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid address" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "super-admin token required" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Get a shared-infrastructure entry", "tags": [ "Admin: shared infrastructure" ] }, "put": { "description": "Updates the name, description, and codehash pin of a shared-infrastructure entry. The address comes from the path (the body address field is ignored); an empty codehash clears the pin. Super-admin token only; the change is audit-logged.", "parameters": [ { "description": "Contract address (0x-prefixed hex)", "in": "path", "name": "address", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.sharedInfraInput", "description": "updated fields (address field ignored)", "summary": "request" } ] } } }, "description": "updated fields (address field ignored)", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.SharedInfrastructure" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid address, invalid body, invalid codehash, or missing name" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "super-admin token required" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Update a shared-infrastructure entry", "tags": [ "Admin: shared infrastructure" ] } }, "/api/v1/admin/shared-infrastructure/{address}/refresh-codehash": { "post": { "description": "Fetches the current bytecode at the entry's address via eth_getCode, computes its keccak256, and stores it as the codehash pin — used after a tracked upstream contract is legitimately upgraded. Verify the new bytecode out of band first. Super-admin token only; the change is audit-logged.", "parameters": [ { "description": "Contract address (0x-prefixed hex)", "in": "path", "name": "address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.SharedInfrastructure" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid address" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "super-admin token required" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "upstream node failed or returned an invalid bytecode hash" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "runtime tracer not configured" } }, "security": [ { "AdminToken": [] } ], "summary": "Refresh a shared-infrastructure codehash", "tags": [ "Admin: shared infrastructure" ] } }, "/api/v1/admin/status": { "get": { "description": "Operational status: proxy liveness and port, upstream node health/latency, compliance/travel-rule configuration, and the extra RPC namespaces/wildcards available to the frontend.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.StatusResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network" } }, "security": [ { "AdminToken": [] } ], "summary": "Proxy status", "tags": [ "Admin: ops" ] } }, "/api/v1/admin/system/eth-call-tracing": { "get": { "description": "Current effective state of the eth_call cross-org tracing control, plus its env default and change metadata. Read-only; any admin the middleware admits.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.systemToggleResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "request processor not initialised" } }, "security": [ { "AdminToken": [] } ], "summary": "Get eth_call cross-org tracing state", "tags": [ "Admin: system" ] }, "post": { "description": "Sets the in-memory eth_call cross-org tracing control. Super-admin token only (tier-2 admin JWTs get 403). A non-empty reason is required and audit-logged. The change is not persisted — a restart re-installs the env default.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.systemToggleRequest", "description": "enabled flag and audit reason", "summary": "request" } ] } } }, "description": "enabled flag and audit reason", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.systemToggleResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing enabled flag, missing reason, or reason too long" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "not a super-admin token, or source address not on the private network" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "request processor not initialised" } }, "security": [ { "AdminToken": [] } ], "summary": "Toggle eth_call cross-org tracing", "tags": [ "Admin: system" ] } }, "/api/v1/admin/system/intra-org-grant-tracing": { "get": { "description": "Current effective state of the RD-1053 intra-org contract-grant scoping control, plus its env default and change metadata. Read-only; any admin the middleware admits.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.systemToggleResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "request processor not initialised" } }, "security": [ { "AdminToken": [] } ], "summary": "Get intra-org grant tracing state", "tags": [ "Admin: system" ] }, "post": { "description": "Sets the in-memory RD-1053 intra-org contract-grant scoping control. Super-admin token only (tier-2 admin JWTs get 403). A non-empty reason is required and audit-logged. The change is not persisted — a restart re-installs the env default. Disabling this control widens intra-org read/send access, so the audit trail matters most on a disable.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.systemToggleRequest", "description": "enabled flag and audit reason", "summary": "request" } ] } } }, "description": "enabled flag and audit reason", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.systemToggleResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing enabled flag, missing reason, or reason too long" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "not a super-admin token, or source address not on the private network" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "request processor not initialised" } }, "security": [ { "AdminToken": [] } ], "summary": "Toggle intra-org grant tracing", "tags": [ "Admin: system" ] } }, "/api/v1/admin/system/version": { "get": { "description": "Build identity (version, commit, build time) of the running binary. Read-only; any admin token. Deliberately not exposed on /health or web3_clientVersion.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.systemVersionResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network" } }, "security": [ { "AdminToken": [] } ], "summary": "Build version of the running proxy", "tags": [ "Admin: system" ] } }, "/api/v1/admin/test-request": { "post": { "description": "Dashboard diagnostic: runs one method through RBAC, travel-rule compliance, and upstream forwarding, using a synthetic identity (\"test:dashboard\") or the subject of a supplied jwt_token. On an upstream JSON-RPC-level error the call still returns HTTP 200 with the error in the response body. Requires the private-network source gate (403 otherwise).", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.TestRequestInput", "description": "method, params, and optional jwt_token / org_id", "summary": "request" } ] } } }, "description": "method, params, and optional jwt_token / org_id", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.TestRequestResponse" } } }, "description": "forwarded result (or an upstream JSON-RPC error message) plus latency" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid request body or invalid JWT" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.TestRequestResponse" } } }, "description": "RBAC or compliance denied (network-gate rejections return the generic error envelope)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.TestRequestResponse" } } }, "description": "access-check error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.TestRequestResponse" } } }, "description": "failed to reach the upstream node" } }, "security": [ { "AdminToken": [] } ], "summary": "Test a JSON-RPC request", "tags": [ "Admin: ops" ] } }, "/api/v1/admin/users": { "get": { "description": "Returns a paginated list of RBAC users, each with a scoped summary of their group memberships. Results are scoped to the caller: a super-admin sees all users, a tier-2 org-admin JWT sees only users in the orgs it administers (full or read-only), and cardinality cannot be used as a cross-org enumeration oracle. The per-user group summary is bounded by the caller's administered orgs, and when org_id is supplied it is further narrowed to that org, so the summary never lists a user's memberships in other orgs. Optional filters: org_id, search, one or more group_id, and role. Tenant-confidential: rejected for the operator token (403).", "parameters": [ { "description": "Restrict to users in this organization", "in": "query", "name": "org_id", "schema": { "type": "string" } }, { "description": "Case-insensitive filter on user identifier", "in": "query", "name": "search", "schema": { "type": "string" } }, { "description": "Restrict to members of these group IDs (repeatable)", "in": "query", "name": "group_id", "schema": { "items": { "type": "string" }, "type": "array" } }, { "description": "Filter by role", "in": "query", "name": "role", "schema": { "enum": [ "org_admin", "admin", "member" ], "type": "string" } }, { "description": "Max rows to return (default 50)", "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "description": "Rows to skip for pagination (default 0)", "in": "query", "name": "offset", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.userListResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid role filter" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, or operator token (tenant data not readable)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "List users", "tags": [ "Admin: RBAC" ] } }, "/api/v1/admin/users/{user_id}": { "delete": { "description": "Deletes a user along with all of their group memberships. Requires full (is_org_admin) scope over an org the user belongs to — read-only admins are rejected. Out-of-scope or unknown users return an opaque 403.", "parameters": [ { "description": "User ID (UUID)", "in": "path", "name": "user_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIMessage" } } }, "description": "user deleted" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, or user outside the caller's full-admin scope (opaque; also covers not-found)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Delete a user", "tags": [ "Admin: RBAC" ] }, "get": { "description": "Returns a single RBAC user by ID. The caller must share at least one org with the user; otherwise the response is an opaque 403 identical to the not-found case, so a tier-2 org-admin JWT cannot distinguish \"exists in another org\" from \"does not exist\". Tenant-confidential: rejected for the operator token (403).", "parameters": [ { "description": "User ID (UUID)", "in": "path", "name": "user_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.User" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, user outside the caller's scope (opaque; also covers not-found), or operator token (tenant data not readable)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Get a user", "tags": [ "Admin: RBAC" ] }, "put": { "description": "Updates a user's kyc, banned, note, and/or metadata fields. All body fields are optional; only supplied fields change. Requires full (is_org_admin) scope over an org the user belongs to — read-only admins are rejected. Banning a user also revokes their refresh tokens for immediate session termination. Out-of-scope or unknown users return an opaque 403.", "parameters": [ { "description": "User ID (UUID)", "in": "path", "name": "user_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.rbacUserUpdateRequest", "description": "fields to update (all optional)", "summary": "request" } ] } } }, "description": "fields to update (all optional)", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.User" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid request body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, or user outside the caller's full-admin scope (opaque; also covers not-found)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Update a user", "tags": [ "Admin: RBAC" ] } }, "/api/v1/admin/users/{user_id}/effective-permissions": { "get": { "description": "Computes and returns the user's resolved permissions (allowed methods, claims, per-contract access) in the given organization — a debugging view of what the RBAC resolver grants. The org is selected by the org query param (slug; defaults to \"default\"). The caller must share the target org with the user, and a tier-2 org-admin JWT must have the queried org in scope, so this cannot be used as a cross-org probe. Tenant-confidential: rejected for the operator token (403).", "parameters": [ { "description": "User ID (UUID)", "in": "path", "name": "user_id", "required": true, "schema": { "type": "string" } }, { "description": "Organization slug to resolve against (default \\", "in": "query", "name": "org", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.EffectivePermissions" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, user or queried org outside the caller's scope (opaque), or operator token (tenant data not readable)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Get a user's effective permissions", "tags": [ "Admin: RBAC" ] } }, "/api/v1/admin/users/{user_id}/linked-addresses": { "get": { "description": "Returns the Ethereum addresses linked to the user's DID, with verification time and any resolved ENS name. The caller must share at least one org with the user; otherwise an opaque 403 (same as not-found). Tenant-confidential: rejected for the operator token (403).", "parameters": [ { "description": "User ID (UUID)", "in": "path", "name": "user_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.userLinkedAddressesResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, user outside the caller's scope (opaque; also covers not-found), or operator token (tenant data not readable)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "List a user's linked ETH addresses", "tags": [ "Admin: RBAC" ] } }, "/api/v1/admin/users/{user_id}/memberships": { "get": { "description": "Returns the user's group memberships (each with the group and a server-computed expired flag for time-boxed grants). For a tier-2 org-admin JWT the list is filtered to the caller's org scope, so a multi-org user's foreign-org memberships are never enumerated. The caller must share at least one org with the user. Tenant-confidential: rejected for the operator token (403).", "parameters": [ { "description": "User ID (UUID)", "in": "path", "name": "user_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/internal_server.membershipListItem" }, "type": "array" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, user outside the caller's scope (opaque), or operator token (tenant data not readable)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "List a user's memberships", "tags": [ "Admin: RBAC" ] }, "post": { "description": "Adds an existing user to a group. Body: group_id (required) and expires_at (optional RFC3339, must be in the future — a time-boxed access window; omit for permanent). Requires full (is_org_admin) scope over the target group's org; the check runs before the body is read so the response is not a user-enumeration oracle. Adding a member to an is_org_admin group is super-admin-only; adding to a regular group is rejected for the operator token. To onboard a not-yet-provisioned DID, use the by-did endpoint instead.", "parameters": [ { "description": "User ID (UUID)", "in": "path", "name": "user_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.membershipCreateRequest", "description": "membership to create", "summary": "request" } ] } } }, "description": "membership to create", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_rbac.UserMembership" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid body or expires_at (must be RFC3339 and in the future)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, target group outside the caller's full-admin scope (opaque), tier-2 JWT adding to an org-admin group, or operator token adding to a regular group" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "user is already a member of this group" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Add a user to a group", "tags": [ "Admin: RBAC" ] } }, "/api/v1/admin/users/{user_id}/memberships/{membership_id}": { "delete": { "description": "Removes a user's membership from a group. Requires full (is_org_admin) scope over the group's org; an unknown or out-of-scope membership returns an opaque 403. Removing a member from an is_org_admin group (a demotion) is super-admin-only; removing from a regular group is rejected for the operator token.", "parameters": [ { "description": "User ID (UUID)", "in": "path", "name": "user_id", "required": true, "schema": { "type": "string" } }, { "description": "Membership ID (UUID)", "in": "path", "name": "membership_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIMessage" } } }, "description": "membership deleted" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid admin token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network, membership's group outside the caller's full-admin scope (opaque; also covers not-found), tier-2 JWT removing from an org-admin group, or operator token removing from a regular group" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "AdminToken": [] } ], "summary": "Remove a membership", "tags": [ "Admin: RBAC" ] } }, "/api/v1/auth/azure/callback": { "post": { "description": "Validates the single-use CSRF state, exchanges the Azure AD authorization code, enforces the tenant allowlist, provisions the RBAC user, and issues our access + refresh tokens. Available only when Azure AD is configured. Rate-limited.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.AzureCallbackRequest", "description": "authorization code, CSRF state, and redirect URI", "summary": "request" } ] } } }, "description": "authorization code, CSRF state, and redirect URI", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.AuthResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid request, redirect_uri not allowed, or invalid/expired state token" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Azure AD authentication failed or invalid tenant ID in token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "tenant not authorized, auto-provisioning disabled, tenant mismatch, or account banned" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Azure AD authentication not configured" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "failed to check tenant authorization, provision user, or issue tokens" } }, "summary": "Complete Azure AD interactive login", "tags": [ "Auth" ] } }, "/api/v1/auth/azure/service-principal": { "post": { "description": "Machine-to-machine login for Azure AD service principals. The client obtains an Azure AD access token out-of-band via the client-credentials grant and posts it here; the proxy verifies it (signature/JWKS, expiry, audience), enforces the tenant allowlist, provisions the RBAC user, and issues our access + refresh tokens. Available only when Azure AD is configured. Rate-limited.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.AzureServicePrincipalRequest", "description": "Azure AD access token from the client-credentials grant", "summary": "request" } ] } } }, "description": "Azure AD access token from the client-credentials grant", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.AuthResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid request format" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Azure AD authentication failed or invalid tenant ID in token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "tenant not authorized, auto-provisioning disabled, tenant mismatch, or account banned" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Azure AD authentication not configured" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "failed to check tenant authorization, provision user, or issue tokens" } }, "summary": "Azure AD service-principal (M2M) login", "tags": [ "Auth" ] } }, "/api/v1/auth/azure/url": { "get": { "description": "Returns the Microsoft Entra ID authorization URL to redirect the user to, plus a single-use CSRF state token to replay at the callback. The `redirect_uri` must be on the server's allowlist. Available only when Azure AD is configured. Rate-limited.", "parameters": [ { "description": "post-login redirect URI (must be allowlisted)", "in": "query", "name": "redirect_uri", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.AzureURLResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "redirect_uri missing or not allowed" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Azure AD authentication not configured" } }, "summary": "Get the Azure AD authorization URL", "tags": [ "Auth" ] } }, "/api/v1/auth/callback": { "post": { "description": "Step 2 of the Privado ID wallet login. The wallet posts the JWZ proof to the session named by the `session` query parameter (the callback URL from step 1). On success the proof is verified and access + refresh tokens are issued. The body is the JWZ token, accepted either as JSON (`{\"token\":\"\u003cjwz\u003e\"}` or `{\"jwz_token\":\"\u003cjwz\u003e\"}`) or as the raw token string; it is size-capped. Rate-limited.", "parameters": [ { "description": "auth session ID from /auth/request", "in": "query", "name": "session", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } }, "text/plain": { "schema": { "title": "request", "type": "object" } } }, "description": "JWZ token, as {\\", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.AuthResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing session parameter, unreadable body, or missing JWZ token" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "session not found/expired, or JWZ verification failed" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.HumanityVerificationError" } } }, "description": "ProofOfHumanity verification required, or account banned" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "failed to persist user record or issue tokens" } }, "summary": "Submit a Privado ID proof (wallet callback)", "tags": [ "Auth" ] } }, "/api/v1/auth/providers": { "get": { "description": "Returns the identifiers of the authentication providers this deployment has configured (always includes \"privado\"; adds \"azuread\" when Azure AD is enabled), so the login UI can render the right options. Public.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.ProvidersResponse" } } }, "description": "OK" } }, "summary": "List configured auth providers", "tags": [ "Auth" ] } }, "/api/v1/auth/request": { "post": { "description": "Step 1 of the Privado ID wallet login. Creates a pending session and returns a session ID plus the authorization request the frontend renders as a QR code for the wallet to scan. The optional body may carry the browser's window.location.origin so the wallet callback URL is reachable from the caller's hostname. Rate-limited.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.AuthRequestBody", "description": "optional callback origin", "summary": "request" } ] } } }, "description": "optional callback origin" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.AuthRequestResponse" } } }, "description": "OK" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "VERIFIER_ID not configured (production) or failed to create the authorization request" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "authentication service at capacity" } }, "summary": "Start a Privado ID authentication session", "tags": [ "Auth" ] } }, "/api/v1/auth/session/{id}/status": { "get": { "description": "The frontend polls this after showing the QR code to learn whether the wallet has completed authentication. While pending it returns `completed:false`; once complete it returns the issued tokens (and mirrors the access JWT into an HttpOnly cookie). Deliberately not rate-limited: it is read-only polling during the login flow.", "parameters": [ { "description": "auth session ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.SessionStatusResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "session ID required" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "session not found or expired" } }, "summary": "Poll a Privado ID auth session for completion", "tags": [ "Auth" ] } }, "/api/v1/auth/verify": { "post": { "description": "Available only in non-production builds. Alternative to the wallet callback: the client submits the session ID and JWZ token in the body, the proof is verified, and access + refresh tokens are issued (also mirrored into an HttpOnly access cookie). Used by the dev mock-login flow. Rate-limited.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.AuthVerifyRequest", "description": "session ID and JWZ token", "summary": "request" } ] } } }, "description": "session ID and JWZ token", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.AuthResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid request body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "session not found/expired, or JWZ verification failed" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.HumanityVerificationError" } } }, "description": "ProofOfHumanity verification required, or account banned" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "failed to persist user record or issue tokens" } }, "summary": "Submit a Privado ID proof manually (dev only)", "tags": [ "Auth" ] } }, "/api/v1/dev/test-identities": { "get": { "description": "Available only in non-production builds with mock login enabled. Returns the pre-configured test users (DIDs with the did:test: prefix), with their linked ETH addresses and org names, to populate the dev identity picker.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.testIdentitiesResponse" } } }, "description": "OK" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "not available" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "failed to list users" } }, "summary": "List dev test identities", "tags": [ "Auth" ] } }, "/api/v1/eth/addresses": { "get": { "description": "Lists the Ethereum addresses linked to the caller's DID, with verification time and any resolved ENS name.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.EthAddressListResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid token" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "BearerAuth": [] } ], "summary": "List linked ETH addresses", "tags": [ "ETH linking" ] } }, "/api/v1/eth/addresses/{address}": { "delete": { "description": "Revokes the link between the address and the caller's DID. A revoked link cannot be re-created without administrator intervention.", "parameters": [ { "description": "ETH address (0x-prefixed hex)", "in": "path", "name": "address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIMessage" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "address parameter required" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid token" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "address not linked to your account" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "BearerAuth": [] } ], "summary": "Unlink an ETH address", "tags": [ "ETH linking" ] } }, "/api/v1/eth/addresses/{address}/refresh-ens": { "post": { "description": "Re-resolves the ENS name for one of the caller's linked addresses and stores the result (which may be empty).", "parameters": [ { "description": "ETH address (0x-prefixed hex)", "in": "path", "name": "address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.EthLinkENSResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "address parameter required" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid token" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "address not linked to your account" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "ENS resolver not configured" } }, "security": [ { "BearerAuth": [] } ], "summary": "Refresh the ENS name of a linked address", "tags": [ "ETH linking" ] } }, "/api/v1/eth/link/challenge": { "post": { "description": "Issues a one-time challenge message for the caller to sign with their Ethereum key, proving key ownership before the address is linked to the authenticated DID. The nonce is single-use and expires after a short TTL.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.ChallengeResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid token" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create an ETH address link challenge", "tags": [ "ETH linking" ] } }, "/api/v1/eth/link/verify": { "post": { "description": "Verifies the signature over the challenge message and links the address to the caller's DID. Fail-closed: an invalid or expired nonce, a challenge issued to a different DID, a malformed address, or a bad signature all reject the link.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.VerifyLinkRequest", "description": "signed challenge", "summary": "request" } ] } } }, "description": "signed challenge", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.EthLinkVerifyResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid body, nonce, address format, or signature" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid token" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "challenge belongs to another user, or the link was revoked by an administrator" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "BearerAuth": [] } ], "summary": "Verify a signed challenge and link the address", "tags": [ "ETH linking" ] } }, "/api/v1/explorer/accounts": { "get": { "description": "Returns a page of accounts (address statistics) plus the count of returned rows. Private network only (serves the explorer backend); not reachable through the public ingress. The response is privacy-filtered for the resolved viewer: accounts hidden from the viewer are dropped, pseudonymous ones have their address masked, and total is the count of returned rows (never the raw DB total).", "parameters": [ { "description": "1-based page number", "in": "query", "name": "page", "schema": { "default": 1, "type": "integer" } }, { "description": "Rows per page (1-100)", "in": "query", "name": "pageSize", "schema": { "default": 25, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": { "items": {}, "type": "array", "uniqueItems": false }, "total": { "example": 25, "type": "integer" } }, "type": "object" } } }, "description": "OK" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "lookup or visibility check failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured" } }, "summary": "List accounts", "tags": [ "Explorer" ] } }, "/api/v1/explorer/addresses/{address}/abi": { "post": { "description": "Stores the ABI JSON for a contract address. Private network only (serves the explorer backend); not reachable through the public ingress. This is privacy-gated: the write requires FULL visibility of the address for the resolved viewer, so only members of the owning org (or a public contract) may update the ABI; other viewers get 404 (indistinguishable from a missing address). The request body is the raw ABI JSON.", "parameters": [ { "description": "Contract address (0x-prefixed hex)", "in": "path", "name": "address", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } }, "text/plain": { "schema": { "title": "request", "type": "object" } } }, "description": "Raw contract ABI JSON (array of ABI entries)", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.ExplorerABIUpdateResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid request body" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "address not found (also returned when the viewer lacks full visibility)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "failed to set contract ABI" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured" } }, "summary": "Set the ABI for a contract", "tags": [ "Explorer" ] } }, "/api/v1/explorer/addresses/{address}/balance": { "get": { "description": "Returns the current native-token balance of an address as a hex-quantity string (forwarded from eth_getBalance). Private network only (serves the explorer backend); not reachable through the public ingress. Access is privacy-filtered: it requires visibility of the address (else 404), so a viewer cannot probe balances of addresses hidden from them.", "parameters": [ { "description": "Account address (0x-prefixed hex)", "in": "path", "name": "address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "hex-quantity balance in wei\" example(0x0)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "address not found (also returned when the address is hidden from the viewer)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "upstream RPC or parse failure" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured" } }, "summary": "Native balance of an address", "tags": [ "Explorer" ] } }, "/api/v1/explorer/addresses/{address}/balances": { "get": { "description": "Returns the token balances held by an address. Private network only (serves the explorer backend); not reachable through the public ingress. The response is privacy-filtered for the resolved viewer: access requires visibility of the address (else 404), and balances of token contracts hidden from the viewer are dropped (pseudonymous token contracts have their address masked).", "parameters": [ { "description": "Account address (0x-prefixed hex)", "in": "path", "name": "address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_explorer.Balance" }, "type": "array" } } }, "description": "OK" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "address not found (also returned when the address is hidden from the viewer)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "lookup or visibility check failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured" } }, "summary": "Token balances of an address", "tags": [ "Explorer" ] } }, "/api/v1/explorer/addresses/{address}/code": { "get": { "description": "Returns the contract bytecode at an address (forwarded from eth_getCode). Private network only (serves the explorer backend); not reachable through the public ingress. Access is privacy-filtered: it requires visibility of the address (else 404). The body is a base64-encoded JSON string wrapping the node's hex code result.", "parameters": [ { "description": "Account address (0x-prefixed hex)", "in": "path", "name": "address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "base64-encoded JSON string of the hex bytecode" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "address not found (also returned when the address is hidden from the viewer)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "upstream RPC or parse failure" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured" } }, "summary": "Deployed bytecode at an address", "tags": [ "Explorer" ] } }, "/api/v1/explorer/addresses/{address}/contract": { "get": { "description": "Returns deployed-contract metadata (bytecode, verification, ABI, source) for an address. Private network only (serves the explorer backend); not reachable through the public ingress. The response is privacy-filtered for the resolved viewer: access requires visibility of the address (else 404), and the creator address is redacted per the viewer's visibility so a private deployer is not revealed.", "parameters": [ { "description": "Contract address (0x-prefixed hex)", "in": "path", "name": "address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_explorer.Contract" } } }, "description": "OK" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "address or contract not found (also returned when the address is hidden from the viewer)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "lookup failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured" } }, "summary": "Contract metadata for an address", "tags": [ "Explorer" ] } }, "/api/v1/explorer/addresses/{address}/internal": { "get": { "description": "Returns a page of internal (trace) transactions involving an address plus the count of returned rows. Private network only (serves the explorer backend); not reachable through the public ingress. The response is privacy-filtered for the resolved viewer: access requires visibility of the address (else 404); rows are redacted per the viewer's visibility and total is the count of returned rows (never the raw DB total).", "parameters": [ { "description": "Account address (0x-prefixed hex)", "in": "path", "name": "address", "required": true, "schema": { "type": "string" } }, { "description": "Max rows to return", "in": "query", "name": "limit", "schema": { "default": 25, "type": "integer" } }, { "description": "Rows to skip (pagination)", "in": "query", "name": "offset", "schema": { "default": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": { "items": {}, "type": "array", "uniqueItems": false }, "total": { "example": 25, "type": "integer" } }, "type": "object" } } }, "description": "OK" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "address not found (also returned when the address is hidden from the viewer)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "lookup or redaction failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured" } }, "summary": "Internal transactions for an address", "tags": [ "Explorer" ] } }, "/api/v1/explorer/addresses/{address}/is-contract": { "get": { "description": "Reports whether an address has deployed code (is a contract). Private network only (serves the explorer backend); not reachable through the public ingress. Access is privacy-filtered: it requires visibility of the address (else 404), so a viewer cannot probe hidden addresses.", "parameters": [ { "description": "Account address (0x-prefixed hex)", "in": "path", "name": "address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.ExplorerIsContractResponse" } } }, "description": "OK" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "address not found (also returned when the address is hidden from the viewer)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "lookup failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured" } }, "summary": "Whether an address is a contract", "tags": [ "Explorer" ] } }, "/api/v1/explorer/addresses/{address}/logs": { "get": { "description": "Returns a page of event logs emitted by an address plus the count of returned rows. Private network only (serves the explorer backend); not reachable through the public ingress. The response is privacy-filtered for the resolved viewer: access requires visibility of the address (else 404); logs are redacted per the viewer's visibility and total is the count of returned rows (never the raw DB total).", "parameters": [ { "description": "Account address (0x-prefixed hex)", "in": "path", "name": "address", "required": true, "schema": { "type": "string" } }, { "description": "Max rows to return", "in": "query", "name": "limit", "schema": { "default": 25, "type": "integer" } }, { "description": "Rows to skip (pagination)", "in": "query", "name": "offset", "schema": { "default": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": { "items": {}, "type": "array", "uniqueItems": false }, "total": { "example": 25, "type": "integer" } }, "type": "object" } } }, "description": "OK" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "address not found (also returned when the address is hidden from the viewer)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "lookup or redaction failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured" } }, "summary": "Event logs for an address", "tags": [ "Explorer" ] } }, "/api/v1/explorer/addresses/{address}/stats": { "get": { "description": "Returns per-address aggregate counts (transactions, internal transactions, token transfers) plus first/last-seen. Private network only (serves the explorer backend); not reachable through the public ingress. The response is privacy-filtered for the resolved viewer: access requires visibility of the address (else 404), and each count is recomputed as the number of rows the viewer can actually see (never the raw total). Fail-closed: a counting error yields 0 for that badge, never the raw aggregate.", "parameters": [ { "description": "Account address (0x-prefixed hex)", "in": "path", "name": "address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_explorer.AddressStats" } } }, "description": "OK" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "address not found (also returned when the address is hidden from the viewer)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "lookup failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured" } }, "summary": "Address statistics", "tags": [ "Explorer" ] } }, "/api/v1/explorer/addresses/{address}/transactions": { "get": { "description": "Returns a page of transactions involving an address, newest first. Private network only (serves the explorer backend); not reachable through the public ingress. The response is privacy-filtered for the resolved viewer: access requires visibility of the address (else 404), and surviving rows are redacted per the viewer's visibility.", "parameters": [ { "description": "Account address (0x-prefixed hex)", "in": "path", "name": "address", "required": true, "schema": { "type": "string" } }, { "description": "Max rows to return", "in": "query", "name": "limit", "schema": { "default": 25, "type": "integer" } }, { "description": "Opaque continuation cursor from the previous response's next_cursor (RD-1149); takes precedence over before", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "Legacy: return rows strictly older than this block number (may skip rows of the boundary block — prefer cursor)", "in": "query", "name": "before", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.AddressTransactionsResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "malformed pagination cursor" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "address not found (also returned when the address is hidden from the viewer)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "lookup or redaction failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured" } }, "summary": "Transactions for an address", "tags": [ "Explorer" ] } }, "/api/v1/explorer/addresses/{address}/transfers": { "get": { "description": "Returns a page of token transfers involving an address, newest first. Private network only (serves the explorer backend); not reachable through the public ingress. The response is privacy-filtered for the resolved viewer: access requires visibility of the address (else 404), and surviving rows are redacted per the viewer's visibility.", "parameters": [ { "description": "Account address (0x-prefixed hex)", "in": "path", "name": "address", "required": true, "schema": { "type": "string" } }, { "description": "Max rows to return", "in": "query", "name": "limit", "schema": { "default": 25, "type": "integer" } }, { "description": "Opaque continuation cursor from the previous response's next_cursor (RD-1149); takes precedence over before", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "Legacy: return rows strictly older than this block number (may skip rows of the boundary block — prefer cursor)", "in": "query", "name": "before", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.AddressTransfersResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "malformed pagination cursor" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "address not found (also returned when the address is hidden from the viewer)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "lookup or redaction failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured" } }, "summary": "Token transfers for an address", "tags": [ "Explorer" ] } }, "/api/v1/explorer/blocks": { "get": { "description": "Returns a page of blocks, newest first. Private network only (serves the explorer backend); not reachable through the public ingress. The response is privacy-filtered for the resolved viewer: each block's transactionCount reflects only transactions the viewer may see.", "parameters": [ { "description": "Max blocks to return", "in": "query", "name": "limit", "schema": { "default": 25, "type": "integer" } }, { "description": "Return blocks strictly older than this block number (pagination cursor)", "in": "query", "name": "before", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_explorer.Block" }, "type": "array" } } }, "description": "OK" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "lookup failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured" } }, "summary": "List recent blocks", "tags": [ "Explorer" ] } }, "/api/v1/explorer/blocks/hash/{hash}": { "get": { "description": "Returns a single block by its hash. Private network only (serves the explorer backend); not reachable through the public ingress. The response is privacy-filtered for the resolved viewer: the block's transactionCount reflects only transactions the viewer may see.", "parameters": [ { "description": "Block hash (0x-prefixed)", "in": "path", "name": "hash", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_explorer.Block" } } }, "description": "OK" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "block not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "lookup failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured" } }, "summary": "Get block by hash", "tags": [ "Explorer" ] } }, "/api/v1/explorer/blocks/latest/number": { "get": { "description": "Returns the highest indexed block number. Private network only (serves the explorer backend); not reachable through the public ingress.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.ExplorerBlockNumberResponse" } } }, "description": "OK" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "lookup failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured" } }, "summary": "Latest block number", "tags": [ "Explorer" ] } }, "/api/v1/explorer/blocks/{number}": { "get": { "description": "Returns a single block by number. Private network only (serves the explorer backend); not reachable through the public ingress. The response is privacy-filtered for the resolved viewer: the block's transactionCount reflects only transactions the viewer may see.", "parameters": [ { "description": "Block number", "in": "path", "name": "number", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_explorer.Block" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid block number" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "block not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "lookup failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured" } }, "summary": "Get block by number", "tags": [ "Explorer" ] } }, "/api/v1/explorer/blocks/{number}/internal": { "get": { "description": "Returns the internal (trace) transactions contained in a block. Private network only (serves the explorer backend); not reachable through the public ingress. The response is privacy-filtered for the resolved viewer: frames fully hidden from the viewer are dropped and surviving rows are redacted per the viewer's visibility.", "parameters": [ { "description": "Block number", "in": "path", "name": "number", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_explorer.InternalTransaction" }, "type": "array" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid block number" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "lookup or redaction failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured" } }, "summary": "Internal transactions in a block", "tags": [ "Explorer" ] } }, "/api/v1/explorer/blocks/{number}/transactions": { "get": { "description": "Returns the transactions contained in a block. Private network only (serves the explorer backend); not reachable through the public ingress. The response is privacy-filtered for the resolved viewer: transactions fully hidden from the viewer are dropped and surviving rows are redacted per the viewer's visibility.", "parameters": [ { "description": "Block number", "in": "path", "name": "number", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_explorer.Transaction" }, "type": "array" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid block number" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "lookup or redaction failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured" } }, "summary": "Transactions in a block", "tags": [ "Explorer" ] } }, "/api/v1/explorer/chain-id": { "get": { "description": "Returns the chain ID for the explorer backend. Private network only (serves the explorer backend); not reachable through the public ingress.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.ExplorerChainIDResponse" } } }, "description": "OK" } }, "summary": "Chain ID", "tags": [ "Explorer" ] } }, "/api/v1/explorer/grant/{grant_id}/activity": { "get": { "description": "Returns activity-log entries (method, status code, timestamp only) for a disclosure grant the caller holds. Private network only (serves the explorer backend); not reachable through the public ingress. The response is privacy-filtered: a valid JWT is required, the viewer DID must match the grant's requester, the grant scope must include activity_logs or full_disclosure, and only entries inside the grant's validity window are returned. Fail-closed: anonymous callers are rejected, and \"grant missing\"/\"not your grant\"/\"expired\" all return the same 404 to prevent enumeration.", "parameters": [ { "description": "Disclosure grant ID", "in": "path", "name": "grant_id", "required": true, "schema": { "type": "string" } }, { "description": "Max rows to return (1-100)", "in": "query", "name": "limit", "schema": { "default": 25, "type": "integer" } }, { "description": "Rows to skip (pagination)", "in": "query", "name": "offset", "schema": { "default": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.GrantActivityLogsResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "grant_id is required" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "grant scope does not include activity_logs" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "grant not found (also returned for a grant that is not yours or has expired)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "lookup failed" } }, "summary": "Grant-scoped activity logs", "tags": [ "Explorer" ] } }, "/api/v1/explorer/grant/{grant_id}/resolve/{address_id}": { "get": { "description": "Resolves an opaque address_id (issued by viewable-addresses) back to grant-scoped disclosure data for the explorer backend. Private network only (serves the explorer backend); not reachable through the public ingress. The response is scoped to the grant's disclosure level: the real address is returned ONLY for a \"full\" grant; a \"pseudonymous\" grant returns a stable pseudonym and no real address; other levels return neither. Fail-closed: a revoked or expired grant, or an address_id that does not belong to the grant, yields 403/404.", "parameters": [ { "description": "Disclosure grant ID", "in": "path", "name": "grant_id", "required": true, "schema": { "type": "string" } }, { "description": "Opaque address identifier from viewable-addresses", "in": "path", "name": "address_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.ResolveAddressResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "grant_id and address_id are required" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "grant has been revoked or has expired" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "grant or address not found for this grant" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "lookup failed" } }, "summary": "Resolve a grant-scoped address_id", "tags": [ "Explorer" ] } }, "/api/v1/explorer/grant/{grant_id}/{address_id}/transactions": { "get": { "description": "Returns transactions for a disclosed address, rendered at the grant's disclosure level. Private network only (serves the explorer backend); not reachable through the public ingress. The response is privacy-filtered for the grant: \"full\" reveals real addresses, hashes and values; \"pseudonymous\" replaces addresses with stable pseudonyms and hides values and hashes; \"redacted\" (or any unknown level) shows only direction, gas, status and timing with \"[PRIVATE]\" counterparties. Fail-closed: a revoked or expired grant, or an address_id that does not belong to the grant, yields 403/404.", "parameters": [ { "description": "Disclosure grant ID", "in": "path", "name": "grant_id", "required": true, "schema": { "type": "string" } }, { "description": "Opaque address identifier from viewable-addresses", "in": "path", "name": "address_id", "required": true, "schema": { "type": "string" } }, { "description": "Max rows to return (1-100). At the scan bounds a page may come back short — even empty — with a next_cursor to continue from (present ⇒ more pages)", "in": "query", "name": "limit", "schema": { "default": 25, "type": "integer" } }, { "description": "Opaque continuation cursor from the previous response's next_cursor (RD-1149); takes precedence over before", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "Legacy: return rows strictly older than this block number (may skip rows of the boundary block — prefer cursor)", "in": "query", "name": "before", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.GrantTransactionsResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "grant_id and address_id are required, or the pagination cursor is malformed" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "grant has been revoked or has expired" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "grant or address not found for this grant" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured or lookup failed" } }, "summary": "Grant-scoped transactions for a disclosed address", "tags": [ "Explorer" ] } }, "/api/v1/explorer/index/block/{number}": { "post": { "description": "Placeholder for manual block indexing. Private network only (serves the explorer backend); not reachable through the public ingress. The proxy has no indexer of its own, so this always responds 500 (not implemented).", "parameters": [ { "description": "Block number", "in": "path", "name": "number", "required": true, "schema": { "type": "integer" } } ], "responses": { "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "manual indexing through proxy not yet implemented" } }, "summary": "Trigger indexing of a block (not implemented)", "tags": [ "Explorer" ] } }, "/api/v1/explorer/logs": { "get": { "description": "Returns event logs matching the given address / topic / block-range filters. Private network only (serves the explorer backend); not reachable through the public ingress. The response is privacy-filtered for the resolved viewer: logs are redacted per the viewer's visibility.", "parameters": [ { "description": "Filter by emitting contract address (0x-prefixed hex)", "example": "0x0000000000000000000000000000000000000001", "in": "query", "name": "address", "schema": { "type": "string" } }, { "description": "Filter by first log topic (event signature hash)", "in": "query", "name": "topic0", "schema": { "type": "string" } }, { "description": "Start block (inclusive)", "in": "query", "name": "from", "schema": { "type": "integer" } }, { "description": "End block (inclusive)", "in": "query", "name": "to", "schema": { "type": "integer" } }, { "description": "Max rows to return (1-1000)", "in": "query", "name": "limit", "schema": { "default": 100, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_explorer.Log" }, "type": "array" } } }, "description": "OK" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "lookup or redaction failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured" } }, "summary": "Query event logs", "tags": [ "Explorer" ] } }, "/api/v1/explorer/search/suggestions": { "get": { "description": "Returns autocomplete suggestions (blocks, transactions, addresses, tokens) for a query string. Private network only (serves the explorer backend); not reachable through the public ingress. The response is privacy-filtered for the resolved viewer: address/contract suggestions hidden or redacted from the viewer are dropped and pseudonymous ones are masked, so private contracts cannot be discovered via autocomplete. An empty query returns an empty list.", "parameters": [ { "description": "Search query (empty returns no suggestions)", "in": "query", "name": "q", "schema": { "type": "string" } }, { "description": "Max suggestions to return (1-50)", "in": "query", "name": "limit", "schema": { "default": 10, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_explorer.SearchSuggestion" }, "type": "array" } } }, "description": "OK" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "search or visibility check failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured" } }, "summary": "Search autocomplete suggestions", "tags": [ "Explorer" ] } }, "/api/v1/explorer/stats": { "get": { "description": "Returns chain-wide aggregate counts (blocks, transactions, addresses, tokens). Private network only (serves the explorer backend); not reachable through the public ingress. The response is privacy-filtered for the resolved viewer: totals reflect only rows the viewer may see, so a restricted viewer sees smaller counts than the raw chain totals.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_explorer.ChainStats" } } }, "description": "OK" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "lookup failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured" } }, "summary": "Chain statistics", "tags": [ "Explorer" ] } }, "/api/v1/explorer/stats/tx-history": { "get": { "description": "Returns a time series of transaction counts bucketed by interval. Private network only (serves the explorer backend); not reachable through the public ingress. The response is privacy-filtered for the resolved viewer: counts reflect only transactions the viewer may see.", "parameters": [ { "description": "Bucket size in minutes", "in": "query", "name": "interval", "schema": { "default": 60, "type": "integer" } }, { "description": "Max buckets to return (1-100)", "in": "query", "name": "limit", "schema": { "default": 30, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_explorer.TxHistoryPoint" }, "type": "array" } } }, "description": "OK" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "lookup failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured" } }, "summary": "Transaction-count history", "tags": [ "Explorer" ] } }, "/api/v1/explorer/sync/catchup": { "get": { "description": "Returns indexer catch-up progress. Private network only (serves the explorer backend); not reachable through the public ingress. The proxy has no indexer of its own, so this always reports a static \"not running\" state.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.ExplorerCatchupProgressResponse" } } }, "description": "OK" } }, "summary": "Catch-up progress", "tags": [ "Explorer" ] } }, "/api/v1/explorer/sync/indexer-progress": { "get": { "description": "Returns indexer backfill progress (min/max fetched block, backfill-complete flag). Private network only (serves the explorer backend); not reachable through the public ingress.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_explorer.IndexerProgress" } } }, "description": "OK" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "lookup failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured" } }, "summary": "Indexer progress", "tags": [ "Explorer" ] } }, "/api/v1/explorer/sync/status": { "get": { "description": "Returns the last indexed block and whether indexing is in progress. Private network only (serves the explorer backend); not reachable through the public ingress.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_explorer.SyncStatus" } } }, "description": "OK" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "lookup failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured" } }, "summary": "Sync status", "tags": [ "Explorer" ] } }, "/api/v1/explorer/tokens": { "get": { "description": "Returns a page of tokens plus the count of returned rows. Private network only (serves the explorer backend); not reachable through the public ingress. The response is privacy-filtered for the resolved viewer: token contracts hidden from the viewer are dropped, redacted/pseudonymous ones have their identifying fields masked, and total is the count of returned rows (never the raw DB total).", "parameters": [ { "description": "Max rows to return (1-100)", "in": "query", "name": "limit", "schema": { "default": 25, "type": "integer" } }, { "description": "Rows to skip (pagination)", "in": "query", "name": "offset", "schema": { "default": 0, "type": "integer" } }, { "description": "Filter by token type (e.g. ERC20, ERC721)", "in": "query", "name": "type", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": { "items": {}, "type": "array", "uniqueItems": false }, "total": { "example": 25, "type": "integer" } }, "type": "object" } } }, "description": "OK" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "lookup or visibility check failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured" } }, "summary": "List tokens", "tags": [ "Explorer" ] } }, "/api/v1/explorer/tokens/{address}": { "get": { "description": "Returns metadata for a single token contract. Private network only (serves the explorer backend); not reachable through the public ingress. The response is privacy-filtered for the resolved viewer: a token hidden or redacted from the viewer returns 404 (same response for both, to avoid an existence oracle); a pseudonymous token has its identifying fields masked; for a fully visible token, holder and transfer counts are recomputed as the number of rows the viewer can see (fail-safe to 0 on error, never the raw aggregate).", "parameters": [ { "description": "Token contract address (0x-prefixed hex)", "in": "path", "name": "address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_explorer.Token" } } }, "description": "OK" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "token not found (also returned when the token is hidden or redacted from the viewer)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "lookup failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured" } }, "summary": "Get token by address", "tags": [ "Explorer" ] } }, "/api/v1/explorer/tokens/{address}/holders": { "get": { "description": "Returns a page of holders of a token contract plus the count of returned rows. Private network only (serves the explorer backend); not reachable through the public ingress. The response is privacy-filtered for the resolved viewer: a token hidden or redacted from the viewer returns 404; holders whose address is hidden from the viewer are dropped and total is the count of returned rows (never the raw DB total).", "parameters": [ { "description": "Token contract address (0x-prefixed hex)", "in": "path", "name": "address", "required": true, "schema": { "type": "string" } }, { "description": "Max rows to return (1-100)", "in": "query", "name": "limit", "schema": { "default": 25, "type": "integer" } }, { "description": "Rows to skip (pagination)", "in": "query", "name": "offset", "schema": { "default": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": { "items": {}, "type": "array", "uniqueItems": false }, "total": { "example": 25, "type": "integer" } }, "type": "object" } } }, "description": "OK" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "token not found (also returned when the token is hidden or redacted from the viewer)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "lookup or redaction failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured" } }, "summary": "Token holders", "tags": [ "Explorer" ] } }, "/api/v1/explorer/tokens/{address}/transfers": { "get": { "description": "Returns a page of transfers of a token contract plus the count of returned rows. Private network only (serves the explorer backend); not reachable through the public ingress. The response is privacy-filtered for the resolved viewer: a token hidden or redacted from the viewer returns 404; surviving transfers are redacted per the viewer's visibility and total is the count of returned rows (never the raw DB total).", "parameters": [ { "description": "Token contract address (0x-prefixed hex)", "in": "path", "name": "address", "required": true, "schema": { "type": "string" } }, { "description": "Max rows to return (1-100)", "in": "query", "name": "limit", "schema": { "default": 25, "type": "integer" } }, { "description": "Rows to skip (pagination)", "in": "query", "name": "offset", "schema": { "default": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": { "items": {}, "type": "array", "uniqueItems": false }, "total": { "example": 25, "type": "integer" } }, "type": "object" } } }, "description": "OK" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "token not found (also returned when the token is hidden or redacted from the viewer)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "lookup or redaction failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured" } }, "summary": "Token transfers", "tags": [ "Explorer" ] } }, "/api/v1/explorer/transactions": { "get": { "description": "Returns a page of transactions, newest first. Private network only (serves the explorer backend); not reachable through the public ingress. The response is privacy-filtered for the resolved viewer: transactions where every participant is hidden are dropped, and surviving rows have addresses and values redacted per the viewer's visibility.", "parameters": [ { "description": "Max rows to return (1-100)", "in": "query", "name": "limit", "schema": { "default": 25, "type": "integer" } }, { "description": "Return rows strictly older than this block number (pagination cursor)", "in": "query", "name": "before", "schema": { "type": "integer" } }, { "description": "Include transaction category tags", "in": "query", "name": "with_categories", "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_explorer.Transaction" }, "type": "array" } } }, "description": "OK" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "lookup or redaction failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured" } }, "summary": "List recent transactions", "tags": [ "Explorer" ] } }, "/api/v1/explorer/transactions/paginated": { "get": { "description": "Returns a page of transactions plus a total count, using page/pageSize pagination. Private network only (serves the explorer backend); not reachable through the public ingress. The response is privacy-filtered for the resolved viewer: rows fully hidden from the viewer are dropped and surviving rows are redacted. Note the total is a SQL-level count that may slightly overcount relative to the redacted rows in data.", "parameters": [ { "description": "1-based page number", "in": "query", "name": "page", "schema": { "default": 1, "type": "integer" } }, { "description": "Rows per page (1-100)", "in": "query", "name": "pageSize", "schema": { "default": 25, "type": "integer" } }, { "description": "Include transaction category tags", "in": "query", "name": "with_categories", "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": { "items": {}, "type": "array", "uniqueItems": false }, "total": { "example": 25, "type": "integer" } }, "type": "object" } } }, "description": "OK" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "lookup or redaction failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured" } }, "summary": "List transactions (page/pageSize)", "tags": [ "Explorer" ] } }, "/api/v1/explorer/transactions/{hash}": { "get": { "description": "Returns a single transaction by hash. Private network only (serves the explorer backend); not reachable through the public ingress. The response is privacy-filtered for the resolved viewer: addresses and values are redacted per the viewer's visibility. Fail-closed: a transaction the viewer cannot see at all returns 404 (indistinguishable from a truly missing hash).", "parameters": [ { "description": "Transaction hash (0x-prefixed)", "in": "path", "name": "hash", "required": true, "schema": { "type": "string" } }, { "description": "Include transaction category tags", "in": "query", "name": "with_categories", "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/privacy-proxy_internal_explorer.Transaction" } } }, "description": "OK" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "transaction not found (also returned when the transaction is fully hidden from the viewer)" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "lookup or redaction failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured" } }, "summary": "Get transaction by hash", "tags": [ "Explorer" ] } }, "/api/v1/explorer/transactions/{hash}/internal": { "get": { "description": "Returns the internal (trace) frames of a transaction. Private network only (serves the explorer backend); not reachable through the public ingress. The response is privacy-filtered for the resolved viewer: frames are redacted per the viewer's visibility, with the parent transaction's own counterparties revealed only to a viewer who is themselves a parent participant.", "parameters": [ { "description": "Transaction hash (0x-prefixed)", "in": "path", "name": "hash", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_explorer.InternalTransaction" }, "type": "array" } } }, "description": "OK" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "lookup or redaction failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured" } }, "summary": "Internal transactions for a transaction", "tags": [ "Explorer" ] } }, "/api/v1/explorer/transactions/{hash}/logs": { "get": { "description": "Returns the event logs emitted by a transaction. Private network only (serves the explorer backend); not reachable through the public ingress. The response is privacy-filtered for the resolved viewer: logs are redacted per the viewer's visibility, with logs of the parent transaction revealed to a viewer who is the transaction's sender or recipient.", "parameters": [ { "description": "Transaction hash (0x-prefixed)", "in": "path", "name": "hash", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_explorer.Log" }, "type": "array" } } }, "description": "OK" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "lookup or redaction failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured" } }, "summary": "Event logs for a transaction", "tags": [ "Explorer" ] } }, "/api/v1/explorer/transactions/{hash}/op-deposit": { "get": { "description": "Returns OP Stack L1 deposit metadata for a transaction. Private network only (serves the explorer backend); not reachable through the public ingress. This deployment is not an OP Stack chain, so this always responds 404.", "parameters": [ { "description": "Transaction hash (0x-prefixed)", "in": "path", "name": "hash", "required": true, "schema": { "type": "string" } } ], "responses": { "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "OP deposit not found (not an OP Stack chain)" } }, "summary": "OP Stack deposit for a transaction (not applicable)", "tags": [ "Explorer" ] } }, "/api/v1/explorer/transactions/{hash}/transfers": { "get": { "description": "Returns the token transfers emitted by a transaction. Private network only (serves the explorer backend); not reachable through the public ingress. The response is privacy-filtered for the resolved viewer: transfers are redacted per the viewer's visibility.", "parameters": [ { "description": "Transaction hash (0x-prefixed)", "in": "path", "name": "hash", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_explorer.TokenTransfer" }, "type": "array" } } }, "description": "OK" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "lookup or redaction failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured" } }, "summary": "Token transfers for a transaction", "tags": [ "Explorer" ] } }, "/api/v1/explorer/transfers": { "get": { "description": "Returns a page of token transfers across all tokens plus the count of returned rows. Private network only (serves the explorer backend); not reachable through the public ingress. The response is privacy-filtered for the resolved viewer: transfers are redacted per the viewer's visibility and total is the count of returned rows (never the raw DB total).", "parameters": [ { "description": "Max rows to return (1-100)", "in": "query", "name": "limit", "schema": { "default": 25, "type": "integer" } }, { "description": "Rows to skip (pagination)", "in": "query", "name": "offset", "schema": { "default": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": { "items": {}, "type": "array", "uniqueItems": false }, "total": { "example": 25, "type": "integer" } }, "type": "object" } } }, "description": "OK" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "lookup or redaction failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "explorer store not configured" } }, "summary": "List all token transfers", "tags": [ "Explorer" ] } }, "/api/v1/explorer/viewable-addresses": { "get": { "description": "Lists the viewer's own linked addresses plus addresses disclosed to them via active disclosure grants. Private network only (serves the explorer backend); not reachable through the public ingress. The response is privacy-filtered for the resolved viewer: the viewer DID comes from a validated JWT (or the impersonation override) — never from a query param — and for non-full grants the disclosed address is a pseudonym or \"[PRIVATE]\", never the real address. Fail-closed: with no resolvable viewer, only empty lists are returned.", "parameters": [ { "description": "Viewer wallet address (0x-prefixed hex), echoed back for display only. The viewer identity is resolved solely from the JWT — a wallet value never resolves a DID (RD-1164 #7).", "example": "0x0000000000000000000000000000000000000001", "in": "query", "name": "wallet", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.ViewableAddressesResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "neither a wallet nor JWT authentication was supplied" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "lookup failed" } }, "summary": "Addresses viewable by the resolved viewer", "tags": [ "Explorer" ] } }, "/api/v1/introspect": { "post": { "description": "OAuth 2.0 token introspection. Accepts a form-encoded `token` (and optional `token_type_hint`) and reports whether it is currently active, with basic metadata for active tokens. Per RFC 7662 the response is always 200 with `active:false` for unknown, expired, or revoked tokens. Rate-limited.", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "oneOf": [ { "type": "string" }, { "title": "token", "type": "string" }, { "title": "token_type_hint", "type": "string" } ] } } }, "description": "the token to introspect | \\" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.IntrospectResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "token is required" } }, "summary": "Introspect a token (RFC 7662)", "tags": [ "Auth" ] } }, "/api/v1/me/admin-status": { "get": { "description": "Whether the authenticated user is a tier-2 org admin or a read-only admin, and in which organizations. A user with no DB record (or only a tier-3 \"admin\" claim) gets is_admin=false.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.MyAdminStatusResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid token" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "BearerAuth": [] } ], "summary": "My admin status", "tags": [ "Profile" ] } }, "/api/v1/me/disclosure/grants": { "get": { "description": "Lists disclosure grants over the authenticated user's data that are currently active (approved, not expired, not revoked) — i.e. who can see the caller's data right now. Scoped to the caller: a user only ever sees grants over their own data. Grant token hashes are never included.", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_disclosure.GrantWithRequest" }, "type": "array" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid token, or no matching user" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "BearerAuth": [] } ], "summary": "List my active disclosure grants", "tags": [ "Disclosure (user)" ] } }, "/api/v1/me/disclosure/grants/all": { "get": { "description": "Lists every disclosure grant over the authenticated user's data, in any state (active, expired, or revoked) — the full access history. Scoped to the caller: a user only ever sees grants over their own data. Grant token hashes are never included.", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_disclosure.GrantWithRequest" }, "type": "array" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid token, or no matching user" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "BearerAuth": [] } ], "summary": "List all my disclosure grants", "tags": [ "Disclosure (user)" ] } }, "/api/v1/me/disclosure/requests": { "get": { "description": "Lists disclosure requests that are pending the authenticated user's decision — i.e. requests targeting the caller's own data. Scoped to the caller: a user only ever sees requests for their own data.", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_disclosure.RequestWithDetails" }, "type": "array" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid token, or no matching user" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "BearerAuth": [] } ], "summary": "List my pending disclosure requests", "tags": [ "Disclosure (user)" ] } }, "/api/v1/me/disclosure/requests/all": { "get": { "description": "Lists every disclosure request targeting the authenticated user's data, in any status (pending, approved, rejected, expired, revoked). Scoped to the caller: a user only ever sees requests for their own data.", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/privacy-proxy_internal_disclosure.RequestWithDetails" }, "type": "array" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid token, or no matching user" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "BearerAuth": [] } ], "summary": "List all my disclosure requests", "tags": [ "Disclosure (user)" ] } }, "/api/v1/me/disclosure/requests/{request_id}/approve": { "post": { "description": "Approves a pending disclosure request that targets the caller's own data, minting an access grant for the requester. A user can only approve requests targeting their own data (otherwise 403). The optional body may narrow (never widen) the granted scope and set the grant duration (defaults to 24 hours). The response returns the new grant without its token hash.", "parameters": [ { "description": "Disclosure request ID", "in": "path", "name": "request_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.ApproveDisclosureRequestBody", "description": "optional scope narrowing, grant duration, and reason", "summary": "request" } ] } } }, "description": "optional scope narrowing, grant duration, and reason" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.DisclosureApproveResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "request cannot be approved (e.g. not pending or expired)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid token, or no matching user" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "request does not target the caller's data" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "request not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "BearerAuth": [] } ], "summary": "Approve a disclosure request", "tags": [ "Disclosure (user)" ] } }, "/api/v1/me/disclosure/requests/{request_id}/reject": { "post": { "description": "Rejects a pending disclosure request that targets the caller's own data; no grant is created. A user can only reject requests targeting their own data (otherwise 403). The request body is optional and carries only a free-text reason.", "parameters": [ { "description": "Disclosure request ID", "in": "path", "name": "request_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.DisclosureReasonBody", "description": "optional rejection reason", "summary": "request" } ] } } }, "description": "optional rejection reason" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.DisclosureStatusResponse" } } }, "description": "status: rejected" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "request cannot be rejected (e.g. not pending)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid token, or no matching user" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "request does not target the caller's data" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "request not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "BearerAuth": [] } ], "summary": "Reject a disclosure request", "tags": [ "Disclosure (user)" ] } }, "/api/v1/me/disclosure/requests/{request_id}/revoke": { "post": { "description": "Revokes a disclosure request the caller previously approved, ending the requester's access to the caller's data. A user can only revoke requests targeting their own data (otherwise 403). The request body is optional and carries only a free-text reason.", "parameters": [ { "description": "Disclosure request ID", "in": "path", "name": "request_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.DisclosureReasonBody", "description": "optional revocation reason", "summary": "request" } ] } } }, "description": "optional revocation reason" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.DisclosureStatusResponse" } } }, "description": "status: revoked" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "request cannot be revoked (e.g. not currently approved)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid token, or no matching user" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "request does not target the caller's data" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "request not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "BearerAuth": [] } ], "summary": "Revoke a disclosure request (user)", "tags": [ "Disclosure (user)" ] } }, "/api/v1/me/orgs": { "get": { "description": "The organizations the authenticated user belongs to, de-duplicated across group memberships.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.MyOrganizationsResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing or invalid token, or user not found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "Internal Server Error" } }, "security": [ { "BearerAuth": [] } ], "summary": "My organizations", "tags": [ "Profile" ] } }, "/api/v1/refresh": { "post": { "description": "Validates the refresh token, rejects it if revoked, expired, or the account is banned, then issues a new access token and rotates the refresh token (the old one is revoked). The access JWT is also refreshed in an HttpOnly cookie. Rate-limited.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.RefreshRequest", "description": "refresh token", "summary": "request" } ] } } }, "description": "refresh token", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.AuthResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid request body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "refresh token invalid, expired, revoked, or not found" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "account is banned" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "failed to check or issue tokens" } }, "summary": "Exchange a refresh token for new tokens", "tags": [ "Auth" ] } }, "/api/v1/revoke": { "post": { "description": "Revokes the supplied refresh token; if an access token is also supplied it is blacklisted for immediate invalidation. The access cookie is cleared. Revocation is best-effort against already-invalid tokens (defense in depth). Rate-limited.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.RevokeRequest", "description": "refresh token, and optional access token", "summary": "request" } ] } } }, "description": "refresh token, and optional access token", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIMessage" } } }, "description": "token revoked successfully" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid request body" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "failed to revoke token" } }, "summary": "Revoke a refresh token (and optionally an access token)", "tags": [ "Auth" ] } }, "/health": { "get": { "description": "Liveness probe. GET returns {\"status\":\"ok\"}; HEAD returns an empty 200.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.healthResponse" } } }, "description": "OK" } }, "summary": "Health check", "tags": [ "System" ] }, "head": { "description": "Liveness probe. GET returns {\"status\":\"ok\"}; HEAD returns an empty 200.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.healthResponse" } } }, "description": "OK" } }, "summary": "Health check", "tags": [ "System" ] } }, "/metrics": { "get": { "description": "Prometheus text exposition of the proxy's metrics. Private-network only.", "responses": { "200": { "content": { "text/plain": { "schema": { "type": "string" } } }, "description": "Prometheus text exposition format" }, "403": { "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "source address not on the private network" } }, "summary": "Prometheus metrics", "tags": [ "System" ] } }, "/oauth/authorize": { "get": { "description": "Starts the OAuth authorization-code flow: validates the parameters and redirect_uri, creates a pending session, and generates the underlying Privado authorization request. Browser clients (Accept: text/html) receive a 302 redirect to the login page; other clients receive JSON with the session IDs and the authorization request to render as a QR code. An optional Bearer JWT may be supplied — when present, the caller's DID is bound to the session as its initiator, enabling later first-party silent SSO; anonymous callers simply complete via the interactive flow. Only response_type=code is supported. Rate-limited.", "parameters": [ { "description": "OAuth client ID", "in": "query", "name": "client_id", "required": true, "schema": { "type": "string" } }, { "description": "client redirect URI (must be allowlisted)", "in": "query", "name": "redirect_uri", "required": true, "schema": { "type": "string" } }, { "description": "opaque CSRF state echoed back to the client", "in": "query", "name": "state", "required": true, "schema": { "type": "string" } }, { "description": "must be \\", "in": "query", "name": "response_type", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.oauthAuthorizeJSONResponse" } } }, "description": "non-browser clients: session IDs and auth request" }, "302": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "browser clients: redirect to the login page" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.OAuthErrorResponse" } } }, "description": "invalid_request or unsupported_response_type" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.OAuthErrorResponse" } } }, "description": "server misconfiguration or failure creating the session" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.OAuthErrorResponse" } } }, "description": "authentication or OAuth service at capacity" } }, "summary": "OAuth 2.0 authorization endpoint", "tags": [ "OAuth SSO" ] } }, "/oauth/callback": { "post": { "description": "The wallet posts the JWZ proof for an OAuth flow, naming both the auth session and the OAuth session via query parameters (the OAuth session must be linked to the given auth session). On success an authorization code is minted and a redirect URL (client redirect_uri with code and state) is returned. The body is the JWZ token, accepted as JSON (`{\"token\":\"\u003cjwz\u003e\"}` or `{\"jwz_token\":\"\u003cjwz\u003e\"}`) or the raw token string; it is size-capped. Rate-limited.", "parameters": [ { "description": "auth session ID", "in": "query", "name": "session", "required": true, "schema": { "type": "string" } }, { "description": "OAuth session ID (must be linked to the auth session)", "in": "query", "name": "oauth_session", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } }, "text/plain": { "schema": { "title": "request", "type": "object" } } }, "description": "JWZ token, as {\\", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.oauthCallbackResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "missing session parameters, unreadable body, or missing/invalid JWZ token" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "session not found/expired, session mismatch, or verification failed" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.HumanityVerificationError" } } }, "description": "ProofOfHumanity verification required, or account banned" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "failed to generate authorization code or build redirect" } }, "summary": "Submit a Privado ID proof for an OAuth session (wallet callback)", "tags": [ "OAuth SSO" ] } }, "/oauth/session/{id}/info": { "get": { "description": "Returns the underlying Privado authorization request for a pending OAuth session so the login page can render its QR code, plus whether the dev mock-complete path is offered. Rate-limited.", "parameters": [ { "description": "OAuth session ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.oauthSessionInfoResponse" } } }, "description": "OK" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "OAuth session or its auth session not found" } }, "summary": "Get pending OAuth session info", "tags": [ "OAuth SSO" ] } }, "/oauth/session/{id}/mock-complete": { "post": { "description": "Available only in non-production builds with mock login enabled. Instantly completes a pending OAuth session with a mock DID (optionally supplied in the body), bypassing Privado verification, and mints the authorization code. Rate-limited.", "parameters": [ { "description": "OAuth session ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } }, "text/plain": { "schema": { "title": "request", "type": "object" } } }, "description": "optional {\\" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.oauthMockCompleteResponse" } } }, "description": "OK" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "mock login not available" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "session not found or expired" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "session already completed" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "failed to complete session" } }, "summary": "Complete an OAuth session with a mock DID (dev only)", "tags": [ "OAuth SSO" ] } }, "/oauth/session/{id}/silent-complete": { "post": { "description": "Production-safe silent SSO. Requires a valid Bearer JWT. Completes a pending OAuth session without the interactive wallet step only when it is fail-closed safe to do so: the caller's DID must equal the session's initiator DID and the session's client must be on the first-party allowlist (an anonymous initiator or a non-first-party client is never eligible and falls through to the interactive flow). On success it mints an authorization code and returns the same shape as the status endpoint. Rate-limited.", "parameters": [ { "description": "OAuth session ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.OAuthSessionStatusResponse" } } }, "description": "completed, with redirect_url" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "silent SSO not available for this session or client" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "session not found or expired" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "session already completed" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "failed to complete session" } }, "security": [ { "BearerAuth": [] } ], "summary": "Silently complete an OAuth session (first-party SSO)", "tags": [ "OAuth SSO" ] } }, "/oauth/session/{id}/status": { "get": { "description": "The frontend polls this during the QR scan to learn whether the user has completed authentication. While pending it returns `completed:false`; once complete it returns the client redirect URL with the authorization code and state. Deliberately not rate-limited: it is read-only polling during the login flow.", "parameters": [ { "description": "OAuth session ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.OAuthSessionStatusResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "session ID required" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "session not found or expired" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "invalid redirect URI" } }, "summary": "Poll an OAuth session for completion", "tags": [ "OAuth SSO" ] } }, "/oauth/token": { "post": { "description": "Exchanges an authorization code for access and refresh tokens. Only grant_type=authorization_code is supported; the code, client_id, and redirect_uri must match the session, the code must be unexpired and unused (single-use). First-party clients must additionally authenticate with their client secret, via HTTP Basic (client_secret_basic) or the client_secret body parameter (client_secret_post). Accepts JSON or form-encoded bodies. Rate-limited.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.OAuthTokenRequest", "description": "authorization-code grant parameters", "summary": "request" } ] } }, "application/x-www-form-urlencoded": { "schema": { "type": "string" } } }, "description": "authorization-code grant parameters", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.OAuthTokenResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.OAuthErrorResponse" } } }, "description": "invalid_request, unsupported_grant_type, or invalid_grant" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.OAuthErrorResponse" } } }, "description": "invalid_client — client authentication failed" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.OAuthErrorResponse" } } }, "description": "server_error — failed to issue or persist tokens" } }, "summary": "OAuth 2.0 token endpoint", "tags": [ "OAuth SSO" ] } }, "/openapi.json": { "get": { "description": "The full generated OpenAPI document for this API — the same file the docs site renders. Regenerated from handler annotations on every merge.", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": {}, "type": "object" } } }, "description": "OpenAPI 3.1 document" } }, "summary": "OpenAPI specification", "tags": [ "System" ] } }, "/rpc": { "post": { "description": "Single Ethereum JSON-RPC 2.0 request, method-allowlisted and RBAC-checked, with per-method response redaction. Batch (array) requests are rejected.\n\n`Authorization: Bearer \u003ctoken\u003e` is OPTIONAL: anonymous callers are restricted to the anonymous method allowlist; authenticated callers get per-method RBAC and response redaction based on their identity.\n\nThe transaction-sending methods (eth_sendTransaction / eth_sendRawTransaction) additionally accept a top-level `visibleTo` array (alias `privateFor`) of DIDs and/or linked ETH addresses, granting those viewers per-transaction visibility of the emitted event logs (RD-1163). It is accepted only for log-emitting contract calls.\n\nA JSON-RPC-level error (bad params, node error, or a masked authorization denial) is returned with HTTP 200 in the JSON-RPC error member. The non-200 statuses below are transport / access / rate-limit failures that never reach the node. `POST /` and `POST /rpc` are the same operation.", "parameters": [ { "description": "Organization the access decision resolves against (only on /rpc/{org_id})", "in": "path", "name": "org_id", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.JSONRPCRequestEnvelope", "description": "JSON-RPC 2.0 request", "summary": "request" } ] } } }, "description": "JSON-RPC 2.0 request", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.JSONRPCResponseEnvelope" } } }, "description": "JSON-RPC response; may carry a JSON-RPC-level error member" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "unreadable body, malformed/batch JSON-RPC, or invalid visibleTo" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "identity required but unresolved on a trace method (debug_traceCall / debug_traceTransaction)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "runtime-trace or compliance denial" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "method not allowed for the caller (denials are masked as method not found)" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "request body too large" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "concurrency limit or upstream rate limit" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "trace-validation or compliance-check error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "failed to forward to the upstream node" } }, "security": [ { "BearerAuth": [] } ], "summary": "Proxied Ethereum JSON-RPC", "tags": [ "JSON-RPC" ] } }, "/rpc/{org_id}": { "post": { "description": "Single Ethereum JSON-RPC 2.0 request, method-allowlisted and RBAC-checked, with per-method response redaction. Batch (array) requests are rejected.\n\n`Authorization: Bearer \u003ctoken\u003e` is OPTIONAL: anonymous callers are restricted to the anonymous method allowlist; authenticated callers get per-method RBAC and response redaction based on their identity.\n\nThe transaction-sending methods (eth_sendTransaction / eth_sendRawTransaction) additionally accept a top-level `visibleTo` array (alias `privateFor`) of DIDs and/or linked ETH addresses, granting those viewers per-transaction visibility of the emitted event logs (RD-1163). It is accepted only for log-emitting contract calls.\n\nA JSON-RPC-level error (bad params, node error, or a masked authorization denial) is returned with HTTP 200 in the JSON-RPC error member. The non-200 statuses below are transport / access / rate-limit failures that never reach the node. `POST /` and `POST /rpc` are the same operation.", "parameters": [ { "description": "Organization the access decision resolves against (only on /rpc/{org_id})", "in": "path", "name": "org_id", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_server.JSONRPCRequestEnvelope", "description": "JSON-RPC 2.0 request", "summary": "request" } ] } } }, "description": "JSON-RPC 2.0 request", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.JSONRPCResponseEnvelope" } } }, "description": "JSON-RPC response; may carry a JSON-RPC-level error member" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "unreadable body, malformed/batch JSON-RPC, or invalid visibleTo" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "identity required but unresolved on a trace method (debug_traceCall / debug_traceTransaction)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "runtime-trace or compliance denial" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "method not allowed for the caller (denials are masked as method not found)" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "request body too large" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "concurrency limit or upstream rate limit" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "trace-validation or compliance-check error" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_server.APIError" } } }, "description": "failed to forward to the upstream node" } }, "security": [ { "BearerAuth": [] } ], "summary": "Proxied Ethereum JSON-RPC", "tags": [ "JSON-RPC" ] } } }, "tags": [ { "description": "Session authentication: Privado ID wallet flow, Azure AD (interactive and service principal), token refresh/revoke/introspection.", "name": "Auth" }, { "description": "OAuth 2.0 endpoints the proxy exposes as an identity provider (used by the block explorer for SSO).", "name": "OAuth SSO" }, { "description": "The proxied Ethereum JSON-RPC endpoint: method allowlist, RBAC, response redaction. Also mounted at POST /.", "name": "JSON-RPC" }, { "description": "Linking Ethereum addresses to the authenticated DID by signature challenge.", "name": "ETH linking" }, { "description": "The authenticated user's own profile.", "name": "Profile" }, { "description": "Disclosure requests and grants, from the data owner's side.", "name": "Disclosure (user)" }, { "description": "Privacy-filtered chain data for the block explorer backend (private network only).", "name": "Explorer" }, { "description": "Organizations, groups, users, memberships, contracts, and grants.", "name": "Admin: RBAC" }, { "description": "Administering disclosure requests.", "name": "Admin: disclosure" }, { "description": "Travel-rule compliance configuration, sanctions lists, and token prices.", "name": "Admin: compliance" }, { "description": "Read-only \"view as user\" mirror: the explorer and JSON-RPC surfaces re-mounted under /api/v1/admin/impersonate/{target_did}/in/{org_id}/..., GET-only, tier-2 admin gated, per-request audited. The mirrored operations are documented once, under their canonical /api/v1/explorer and /rpc paths.", "name": "Admin: impersonation" }, { "description": "Fleet-level shared contract infrastructure and Azure tenant administration.", "name": "Admin: shared infrastructure" }, { "description": "Fleet-level system toggles and build identity.", "name": "Admin: system" }, { "description": "Operational admin endpoints: access logs, status, and test requests.", "name": "Admin: ops" }, { "description": "Health, metrics, and this specification.", "name": "System" } ] }