Tags, groups and roles

Rules rarely name single devices. They name sets: "the database servers", "the SRE team", "every admin". Peerlify gives you three kinds of sets:

There is also email:<address> for one person's devices, * for every device, and client: and ip: for single devices. See Choose selectors that last for when to use which.

Tags

A tag is a label you put on devices, such as prod, db or build-server. Rules refer to it as tag:prod.

Create a tag

1. Open Access → Tags.
2. Under New tag, type the name and click Add tag.

Tag names may contain only lowercase letters, digits and dashes. Creating tags requires the Owner, Admin or Network admin role.

Apply tags to a device

1. Open Devices and find the device.
2. Open the ⋯ menu in its row and choose Edit tags. The same action is under Actions on the device's page.
3. Choose the tags and save. The dialog replaces the device's whole set of tags.

The tags must already exist. You can add or remove only tags you manage (see below). Applying tags requires the Owner, Admin or IT admin role.

To tag devices as they enroll, an admin can create an auth key with Auto-assign tags. Each time a device signs in with that key, the key's tags replace the device's tags. Tag names in the key that don't exist in the network are skipped.

Tagged devices are shared resources

A device with at least one tag no longer belongs to the person who signed it in. The console shows it as Shared resource, and:

• email:, group: and role: selectors no longer match it. Only tag:, client:, ip: and * do.
• It can't switch networks with peerlify network swap.
• If you remove its last tag, its session is revoked and it must sign in again.

A device that signs in through the browser (peerlify login without a key) has its tags removed, because the person who approved the sign-in becomes its owner.

Delete a tag

Click the trash icon next to the tag in Access → Tags. The tag is deleted immediately, with no confirmation.

Who can manage a tag

Each tag has a list of managers. Managing a tag means you can:

• add it to or remove it from devices,
• delete it or change its managers,
• write a rule that newly refers to it. Writing a rule around a tag grants access through it, so it takes the same permission.

Each action also needs the matching role: applying tags to devices needs Owner, Admin or IT admin; deleting a tag or changing its managers needs Owner, Admin or Network admin.

A tag with no managers listed is managed by role:admin and role:it-admin. The network Owner can always manage every tag.

Each tag's row in Access → Tags shows its current managers on the Managed by line, marked (default) when none are set. To change them, click the people icon next to the tag (Edit managers). The Managers for dialog has toggles for the built-in role groups and a field for email addresses and group: names. You must already be a manager to change the list. Naming managers replaces the default: if you hand tag:prod to group:sre, admins can no longer manage it.

Groups

A group is a named list of people, declared inside the policy:

"groups": {
  "group:sre": ["alice@example.com", "bob@example.com"],
  "group:platform": ["carol@example.com", "group:sre"]
}

• Keys must start with group:.
• Members are plain email addresses of people in the network, or other groups. Members written with a prefix, such as email:alice@example.com, match nothing.
• Groups can be nested. A cycle (group:a contains group:b, which contains group:a) is rejected when you save.
• A rule that refers to a group that isn't declared, and isn't an active synced group, saves without error and matches nothing.
• A group that lists an undeclared group as a member is rejected when you save. The one exception is a reference the saved policy already contained, such as a synced group your identity provider has since deleted: it is kept so other edits still save, and it matches nothing.
• Groups you declare are maintained only in the policy. On the Enterprise plan, groups can also come from your identity provider: see Synced groups.

Edit groups in Access → Groups. Renaming a group there does not update rules that use the old name.

The number of groups is limited by plan: Personal 2, Personal+ 5, Team 20, Business 500, Enterprise unlimited. See Plans and limits.

Synced groups

With user and group provisioning, groups from Microsoft Entra ID or Okta appear in Access → Groups under Synced groups. They are read-only: their members change only at your identity provider, and those changes reach devices within about 10 seconds.

• A synced group is named group:<name>@<domain>, for example group:security-team@example.com for Security Team. The name is fixed when the group is first synced: renaming the group at your identity provider changes only the name shown in the console, so rules keep working.
• Use it in rule sources and destinations, shadowing rules, exit-point rule sources, inside your own groups, and as a tag manager (see Who can manage a tag). It can't assign roles.
• It matches the devices of members who are linked to their sign-in and not suspended by your identity provider.
• If your policy already declares a group with the same name, your group keeps its meaning and the synced group shows Name conflict, matching nobody. You can't add a policy group with the name of an active synced group.
• Synced groups don't count toward the plan's group limit.
• When your identity provider deletes a group, rules that refer to it match nobody.

Role groups

Every network has seven built-in groups whose membership follows each member's role:

They can't be edited; change someone's role instead. Only approved members count. A misspelled role, such as role:admins, matches nobody. The older spelling peerlifygroup:<role> still works and is treated as role:<role>.

Which devices a person-based selector covers

email:, group: and role: are expanded by the control plane into the person's devices. A device counts when:

• the person is a member of the network,
• they have an active session on it (not expired, not revoked), and
• the device has no tags.

Changes, such as a new sign-in, a role change or a new group member, reach devices within about 10 seconds without editing the policy.

Next steps

• Choose selectors that last
• Auth keys
• Members and roles