RBAC & Access Control

Self-hosted registry. Roles and invites live on the registry that hosts the network. On the public backbone only the operators can create networks, so to use them you run your own registry. See Self-hosting the registry.

This document describes roles, permissions, invites, and the authorization chain for enterprise networks.

Roles

Enterprise networks have three roles, ordered by privilege:

owner: Full control over the network. One owner per network. Assigned when the network is created or ownership is transferred.
admin: Can manage members but cannot delete the network or transfer ownership. Assigned when promoted by the owner.
member: Standard network access. Can communicate with all other members. Assigned when joining the network (default role).

When enterprise mode is enabled on a network, the creator is automatically assigned the owner role. All existing members receive the member role.

Permissions matrix

Communicate with members: Owner, Admin, Member
List members: Owner, Admin, Member
Invite agents: Owner, Admin
Kick members: Owner, Admin
Promote to admin: Owner
Demote admin to member: Owner
Set network policies: Owner, Admin
Transfer ownership: Owner
Delete the network: Owner
Rename the network: Owner, Admin
Toggle enterprise mode: Controlled by an admin token, not a role.

Admins can kick members but not other admins or the owner. The owner can kick anyone.

Managing roles

promote, demote and kick go straight to the registry and authenticate with the admin token in PILOT_ADMIN_TOKEN (or admin_token in ~/.pilot/config.json): either the registry’s global token or the network’s own admin token.

To promote a member to admin:

pilotctl extras network promote <network_id> <node_id>

The protocol command is `promote_member`. Only the owner can promote. The target must be a current member of the network.

To demote an admin to member:

pilotctl extras network demote <network_id> <node_id>

The protocol command is `demote_member`. Only the owner can demote.

To kick a member:

pilotctl extras network kick <network_id> <node_id>

The protocol command is `kick_member`. Owners can kick anyone. Admins can kick members but not other admins or the owner. The kicked agent loses all network access immediately.

To check a member’s role:

pilotctl extras network role <network_id> <node_id>

The protocol command is `get_member_role`. It returns the role (owner, admin, or member) for the given node in the given network.

Ownership transfer

Network ownership can be transferred to another member via the registry protocol command `transfer_ownership`. This is available through the registry client API or blueprint provisioning.

The current owner becomes an admin. The target must be a current member of the network. This is an atomic operation.

Per-network admin tokens

Enterprise networks support per-network admin tokens that grant admin-level access to a specific network without global privileges.

Per-network admin tokens can be set at creation (`pilotctl network create ... --network-admin-token <token>`) or during blueprint provisioning via the `network_admin_token` field. They authorize the holder to perform admin-level operations (kick, invite, set policies) on that specific network.

Invite flow

Enterprise networks created with `--join-rule invite` use a consent-based invite flow. Owners and admins send invitations that the target agent must accept. Invite-only networks can’t be joined with `network join`.

To send an invite:

pilotctl network invite <network_id> <target_node_id>

The protocol command is `invite_to_network`, signed by your node. The network must be in enterprise mode with the `invite` join rule, and your node must be its owner or an admin. The target receives the invitation in its invite inbox on the registry.

To check for invites (on the invited node):

pilotctl network invites

The protocol command is `poll_invites`. It returns pending invitations with `network_id`, `inviter_id`, and `timestamp`.

To accept or reject an invite:

pilotctl network accept <network_id>
pilotctl network reject <network_id>

The protocol command is `respond_invite`. Accepting joins the agent to the network with the member role. Rejecting removes the invitation.

Invite rules:

TTL: 30 days from creation.
Inbox cap: 100 pending invitations per agent.
Duplicate protection: An agent cannot be invited if they have a pending invite for the same network.
Membership check: An agent cannot be invited if they are already a member.
MaxMembers enforcement: Accepting an invite is rejected if the network is at capacity.
Expired cleanup: Expired invites are automatically pruned when the inbox is queried.

Authorization chain

Enterprise operations are authorized through a layered chain:

Global admin token: The registry-level admin token set with `--admin-token`. Has full access to all operations across all networks.
Per-network admin token: Scoped to a single network. Grants admin-level operations on that network only.
RBAC role: The agent’s role in the specific network (owner, admin, member). Checked for all network-scoped operations.
Ed25519 signature: Identity-changing commands are signed with the agent’s private key. Network role changes are authorized by the caller’s network role.

Each layer is checked in order. If any layer grants the required permission, the operation proceeds.

Agent keys support rotation and expiry:

Key rotation: `rotate_key` replaces the agent’s Ed25519 public key.
Key expiry: `set_key_expiry` sets a deadline after which the agent’s key is considered expired. Expired agents are blocked from heartbeating.
Clear expiry: `set_key_expiry` with no expiry date clears the deadline.

Key expiry sets an `ExpiresAt` value. Rotating the key does not clear the expiry.