Service Integration

This document explains how external services (such as indexers) can integrate with Prividium to access chain data and verify user permissions.

Overview

Services can integrate with Prividium in two ways:

Service RPC Endpoint - Access chain data for indexing (blocks, logs, transactions)
Check Read Access Endpoint - Verify if a user has read permissions before serving data

Service Authentication

Services authenticate using a service token in the Authorization header. The Prividium™ api validates that the caller is a registered service entity before processing requests.

Service RPC Access

Available Methods

The following JSON-RPC methods are available for services (typically used for chain indexing):

Method	Description
`eth_blockNumber`	Get the current block number
`eth_getLogs`	Query event logs with filters
`eth_getTransactionByHash`	Get transaction details by hash
`eth_getTransactionReceipt`	Get transaction receipt by hash
`eth_getBlockByNumber`	Get a block by block number

Example Request

curl -X POST http://localhost:8000/rpc \
  -H "Authorization: Bearer <service_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_blockNumber",
    "params": [],
    "id": 1
  }'

Example Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x1a2b3c"
}

Verifying User Read Access

When a service needs to serve indexed data to a user, it should verify that the user has read permissions.

Endpoint

POST http://localhost:8000/api/service-actions/check-read-access

Request Body

Field	Type	Required	Description
`userId`	string	Yes	The user ID to check access for

Response

Field	Type	Description
`authorized`	boolean	`true` if user has read access, `false` otherwise

Permission Logic

A user has fullReadAccess if any of the following conditions are met:

User has the admin role
User has the full_read_access system permission

Example Request

curl -X POST http://localhost:8000/api/service-actions/check-read-access \
  -H "Authorization: Bearer <service_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123456"
  }'

Example Response

{
  "authorized": true
}

Integration Flow

A typical integration flow for a webhook service:

Loading diagram...

Configure Webhook: User sends webhook configuration along with their session token
Identify User: Service calls GET /api/profiles/me with the user's session token to retrieve the user profile and ID
Check Access: Service calls POST /check-read-access with the user ID to verify read permissions
Store Configuration: If access is granted, store the webhook configuration; otherwise, return an error
Periodic Re-check: Service periodically re-validates user permissions and disables webhooks for users who no longer have access