Manage M2M Applications

M2M applications represent machine principals that authenticate programmatically against Prividium. Unlike OAuth applications, they do not handle end-user login flows. Unlike tenants, they do not manage users. Instead, they use a set of assigned roles to access RPC methods and event data.

Prividium is moving machine-to-machine integrations toward M2M applications over time. Use M2M applications as the forward-looking model for new machine principals.

Overview

• Roles: Assigned roles are used for RPC authorization and event visibility checks.
• Credentials: The admin UI manages API keys for programmatic authentication.
• Network Restrictions: API-key authentication is allowed only from whitelisted IP addresses.
• Organizations: M2M applications can be linked to one or more organizations to act on behalf of their users.

Manage M2M Applications

Admins manage M2M applications directly through the dashboard.

1. Open the M2M Applications page

1. Go to the Admin Dashboard.
2. Select M2M Apps from the sidebar.
3. Review the list of M2M applications with their names, assigned roles, and descriptions.

2. Create an M2M application

1. Click New M2M app.
2. Fill in the application details:
   • M2M App Name (required): A descriptive name for the machine principal.
   • Description: Optional summary of the application or workload.
3. Assign one or more Roles.
4. Click Create M2M App.

3. Edit an M2M application

1. Click the application row in the list.
2. Click Edit M2M App.
3. Update the name, description, or assigned roles.
4. Click Save Changes.

The detail view also displays read-only metadata:

• M2M App ID
• Created At
• Updated At

4. Delete an M2M application

1. Open the application by clicking its row.
2. Click Delete M2M App.
3. Confirm the deletion.

Authentication Model

The admin UI manages API-key access for M2M applications. It does not expose a public key, wallet address, or other signing identity field for M2M apps.

API Key Authentication

API keys provide an alternative server-to-server authentication method when interactive wallet signing is not practical. Admins create and revoke these credentials from the M2M application detail page.

API Keys

Create an API Key

1. Open an M2M application.
2. Go to the API Keys tab.
3. Click Add API Key.
4. Enter a Name for the key.
5. Select an Expiration Date.
6. Click Create.

Manage API Keys

The API Keys tab displays:

To revoke a key:

1. Find the key in the list.
2. Click Revoke.
3. Confirm the action.

Revoked keys are invalid immediately and cannot be restored.

IP Whitelisting

IP whitelisting restricts which source IP addresses can authenticate with API keys for an M2M application. Entries can be individual IP addresses or CIDR ranges (e.g., 10.42.0.0/16).

Add an IP Address

1. Open an M2M application.
2. Go to the IP Whitelist tab.
3. Click Add IP Address.
4. Enter an IP Address in IPv4 or IPv6 format, or a CIDR range (e.g., 10.42.0.0/16, 2001:db8::/32).
5. Optionally add a Description.
6. Click Add.

Overbroad entry warnings

The admin panel flags overbroad entries per application. The IP Whitelist tab marks each overbroad entry with an "Allows any IP" badge and shows a warning callout while any such entry exists. The M2M applications list shows the same badge next to affected apps. Remove or tighten the flagged entries to restore IP restrictions.

Remove an IP Address

1. Find the IP address in the list.
2. Click Remove.
3. Confirm the action.

Organizations

M2M applications can be linked to one or more organizations. Linked organizations determine which users and wallets the M2M app can act on behalf of when using organization-scoped system permissions such as m2m_org_rpc_access, m2m_org_users_manage, and m2m_org_wallets_manage.

Link an organization

1. Open an M2M application.
2. Go to the Organizations tab.
3. Click Add Organization.
4. Search for the organization by name.
5. Click the organization row to link it.

Remove a linked organization

1. Open an M2M application.
2. Go to the Organizations tab.
3. Find the organization in the list.
4. Click Remove.
5. Confirm the action.

Org-owned credentials

Organization admins can create M2M credentials that belong to their own organization, managed from the organization's admin panel. These are distinct from the zone-level credentials above, which an operator owns and links to organizations: a zone-level credential is read-only to org admins, while an org-owned credential is fully theirs to create, update, and delete.

List credentials visible to an organization

GET /api/organizations/:id/m2m-applications

Returns both org-owned credentials and the zone-level credentials the operator assigned to the org. Zone-level credentials have organizationId: null; org-owned credentials carry the organization's ID.

Create an org-owned credential

POST /api/organizations/:id/m2m-applications

Request body:

{
  "name": "billing-bot",
  "description": "optional description",
  "roles": [{ "roleName": "org-role-name" }]
}

Roles must belong to the organization: zone-level, peer-org, or nonexistent role names all return 404 Not Found without disclosing which. A role that exists in the org but grants permissions beyond the org-admin ceiling (anything other than org_users_manage, org_wallets_manage, or org_rpc_access) is rejected with 400 Bad Request.

Update an org-owned credential

PUT /api/organizations/:id/m2m-applications/:appId

The request body has the same shape as create, and roles are validated against the same ceiling. Only org-owned credentials respond to this route; zone-level credentials assigned to the org return 404 Not Found.

Delete an org-owned credential

DELETE /api/organizations/:id/m2m-applications/:appId

Only org-owned credentials can be deleted. Zone-level credentials return 404 Not Found.

Organization User Management

M2M applications linked to organizations can programmatically manage users and wallets within those organizations. These capabilities are controlled by system permissions assigned to the M2M app's role.

org_users_manage

Allows the M2M app to create and list users within its linked organizations. Users created this way are automatically assigned the organization's default roles.

org_wallets_manage

Allows the M2M app to attach wallet addresses to users in its linked organizations. All wallet addresses must be fresh EOAs: not already registered in the system, with nonce 0, and not a smart contract.

Creating a user with wallet addresses in a single request requires both org_users_manage and org_wallets_manage.

Organization-Scoped RPC Access

M2M applications can be linked to organizations and granted the org_rpc_access system permission, allowing them to make RPC calls on behalf of organization users. The authorization model differs between contract calls and event queries:

Contract reads (eth_call, eth_estimateGas)

When the M2M app makes a read call with a from address:

1. The system verifies the M2M app has org_rpc_access.
2. It looks up the user who owns the from wallet within the app's linked organizations.
3. It checks that user's own roles against the contract's function permission.

The M2M app's roles are not used for this check. The individual user must hold the required role for checkRole permissions to pass.

Contract writes (eth_sendRawTransaction)

When the M2M app submits a signed transaction:

1. The signer address is recovered from the raw transaction.
2. The same authorization flow as contract reads applies: the system verifies org_rpc_access, looks up the signer within linked organizations, and checks that user's roles against the contract's function permission with write access.
3. Transfers to externally-owned accounts (EOAs) skip the permission check entirely.

Contract deployment

Contract creation (a transaction with no to address) needs contract_deployment in addition to org_rpc_access, and grants it in two places:

1. The M2M app's own roles must include contract_deployment.
2. The recovered signer must be a wallet of a user in a linked organization, and that user's roles must also include contract_deployment.

The API key alone is therefore not enough to deploy — the transaction must be signed by a wallet belonging to a permitted user. The deployment is recorded against that user, while the audit log records the M2M app and the API key used.

eth_feeHistory and eth_estimateGas for a creation call sit behind the same permission, so a missing grant surfaces during fee estimation before the deployment transaction is submitted.

Event queries (eth_getLogs)

When the M2M app queries logs:

1. The system verifies the M2M app has org_rpc_access.
2. It collects all wallet addresses across all linked organizations.
3. It checks the M2M app's roles against event permissions.

Individual user roles are not consulted. The M2M app's roles act as a blanket for all organization users.

Setup implications

• For contract method access: the M2M app needs a role with org_rpc_access, and each user it acts on behalf of needs a role that satisfies the contract's function permission (e.g., a role listed in a checkRole rule). These can be different roles.
• For event log access: assign the role only to the M2M app. Users do not need the role individually.

Query Endpoints

M2M applications can read permission and contract metadata from Prividium through query endpoints under /m2m-app-queries. These are intended for integrations like webhook services and indexers that need to verify user access or fetch contract details without making full RPC calls. Each endpoint is gated by a dedicated system permission.

All requests authenticate with the M2M app's API key in the x-api-key header and must originate from a whitelisted IP address.

Check user read access

POST /m2m-app-queries/check-user-read-access

Returns whether a given user has full read access to chain data. Useful before registering or firing a webhook on behalf of that user.

Requires the check_user_read_access system permission on one of the M2M app's roles.

Request body:

{ "userId": "usr_..." }

Response:

{ "authorized": true }

authorized is true when the user has the admin role or the full_read_access system permission, and false otherwise. Returns 404 if the user does not exist.

Read contract metadata

GET /m2m-app-queries/contracts/:contractAddress

Returns the full contract record (address, name, description, ABI, disclosed addresses, template, disclosure flags) for a registered contract.

Requires the contract_metadata_read system permission on one of the M2M app's roles. Returns 404 if no contract is registered at the given address.

How M2M Applications Differ From Other App Types

Compared to OAuth Applications

M2M applications do not have:

• OAuth client IDs
• redirect URIs
• whitelisted browser origins
• user-facing login flows
• a public key field in the admin UI

OAuth applications are for end-user authentication. M2M applications are for machine principals.

Compared to Tenants

M2M applications do not:

• create or manage users
• assign default roles to tenant-created users
• aggregate visibility across a tenant's managed users

Tenants model third-party user-management systems. M2M applications model machine principals with roles. Over time, M2M applications are expected to replace tenant-based setups for machine-only integrations.