{"slug":"group-devices-with-tags","title":"Group devices with tags","tags":["tailscale","devices"],"agent_summary":"Last validated: Dec 4, 2025","trigger_phrases":[],"runnable":false,"markdown":"\r\n# Group devices with tags\r\n\r\nLast validated: Dec 4, 2025\r\n\r\nTagsare available for [all plans](https://tailscale.com/pricing).\r\n\r\nAll plans include 50 tagged devices. If you need more than 50 tagged devices, contact our [Sales team](https://tailscale.com/contact/sales).\r\n\r\nTailscale tags are how you authenticate and identify non-user devices, such as servers and [ephemeral nodes](https://tailscale.com/docs/features/ephemeral-nodes). They serve two primary purposes: to provide an identity to non-user devices and to let you manage [access control policies](https://tailscale.com/docs/features/access-control) based on _purpose_. In this context, a purpose could be anything from hosting a web server to serving as a [subnet router](https://tailscale.com/docs/features/subnet-routers) for employees in a specific geographic location.\r\n\r\nTags are essentially service accounts, but with more flexibility⎯you can assign multiple tags to a device to account for multiple purposes. For example, you might have a device that runs a PostgreSQL database and serves as a web server for internal access. In such a scenario, you could assign the device the following tags (each of which you could target individually using access control policies): `tag:postgresql`, `tag:internal-access`, and `tag:web-server`.\r\n\r\nOther key characteristics of tags include:\r\n\r\n- Applying a tag to a device removes any user-based authentication.\r\n- Each non-user device can have as many tags as you need.\r\n- Tags are defined in the tailnet policy file in the `tagOwners` section.\r\n- Only designated tag owners can apply tags to devices; each tag can have as many owners as necessary.\r\n\r\n## [Requirements](https://tailscale.com/docs/features/tags\\#requirements)\r\n\r\nTags are a free feature and are available for all pricing plans. However, you must have permission to perform some tag-related operations:\r\n\r\n- You must be an [Owner, Admin, or Network admin](https://tailscale.com/docs/reference/user-roles) of a tailnet to define a tag in the tailnet policy file.\r\n- You must be a tag owner to assign a tag to a device. [Owner, Admin, or Network admin](https://tailscale.com/docs/reference/user-roles) can apply any tag, even if they don't own the tag.\r\n\r\n## [Limitations](https://tailscale.com/docs/features/tags\\#limitations)\r\n\r\nTags have the following limitations and restrictions:\r\n\r\n- You cannot remove all tags from a device. A device with a tag-based identity must have at least one tag.\r\n- You cannot remove tags using the `--advertise-tags` flag if the device uses an auth key. Instead, generate a new auth key with the latest set of tags.\r\n- [IP sets](https://tailscale.com/docs/features/tailnet-policy-file/ip-sets) do not support tags.\r\n- Devices with a tag-based identity can only SSH into other tagged devices; they cannot SSH into devices with a user-based identity.\r\n- Some restrictions exist around using tags to define a group or as the SSH source.\r\n\r\n## [Use cases](https://tailscale.com/docs/features/tags\\#use-cases)\r\n\r\nTags are ideal for managing devices you don't want to link to a specific user (such as a server hosting a web application) because removing a user also removes all their devices. If you link a service-providing device to a user, you lose that device if you remove the user. Removing a user won't affect the device if you use tags to manage the device instead. Do not use tags to associate a user device with a user account. Tags are not designed to tie individual users to a device. They're intended to manage devices with service account roles. Using tags as a substitute for users poses a security risk because the user's devices will remain on your network even if you remove the user.\r\n\r\nTags provide a way to allow multiple users to manage a device. When you manage devices with users, you must link each device to a single user, which isn't ideal for devices that host shared resources. However, when you manage devices with tags, you can assign one or more users as tag owners with tags. These users can manage all the devices with the tags they own.\r\n\r\n**Warnings about tags**\r\n\r\nOnly use tags for non-human machines. Users can only access and use Tailscale through their designated user accounts. Using tags to annotate user devices is poor practice because a device cannot simultaneously have a user and a tag. Adding a tag to a device removes the associated user. Devices can have tags or a user account, not both.\r\n\r\nUse tags to:\r\n\r\n- Manage devices you don't have tied to a specific user (such as a server hosting a web application).\r\n- Manage devices you want to allow multiple users to manage.\r\n\r\nDo not use tags to:\r\n\r\n- Annotate user devices.\r\n- Link a user device with a user.\r\n- Authenticate end-user devices, such as laptops or mobile devices.\r\n\r\n## [Ownership](https://tailscale.com/docs/features/tags\\#ownership)\r\n\r\nThere's no \"tag\" section of the tailnet policy file. Instead, you define tags by their owners in the `tagOwners` section of the tailnet policy file. Only owners of a tag can apply that tag to devices in your Tailscale network (known as a tailnet). Tag owners can be users, groups, or even other tags, which means you can create complex tag [ownership hierarchies](https://tailscale.com/docs/features/tags#advanced-tag-hierarchies).\r\n\r\nA tagged device's identity is the combination of all its tags (not the intersection). You can assign any number of tags to a device and manage the permissions for each tag separately. For example, if you have a device with the tags `tag:postgresql`, `tag:prod`, and `tag:ci-cd`, an access control policy for any one of these tags would apply to the device.\r\n\r\n[Owner, Admin, or Network admin](https://tailscale.com/docs/reference/user-roles) can apply any tag, even if they aren't tag owners.\r\n\r\n## [Tag vs. user authentication](https://tailscale.com/docs/features/tags\\#tag-vs-user-authentication)\r\n\r\nTags are parallel to user authentication. They serve the same role as a user account, except they're intended for service-based devices, such as a web server or an app connector. As a result, it's impossible for a user account identity and a tag identity to exist on the same device. Applying a tag to a device previously authenticated with a user account removes the user account. Similarly, authenticating a device with a user account removes all tags from the device.\r\n\r\nBecause tags are for non-user devices, they have qualities and limitations that make them unsuitable for authenticating end-user devices, such as a MacBook or a mobile device. For example, devices with a tag-based identity cannot use SSH to connect to a device with a user-based identity.\r\n\r\n## [Key expiry](https://tailscale.com/docs/features/tags\\#key-expiry)\r\n\r\nWhen you apply a tag to a device for the first time and authenticate it, the tagged device's key expiry is disabled by default.\r\n\r\nIf you re-authenticate a device tagged before March 10, 2022, its expiry will be disabled by default.\r\n\r\nIf you change the tags on the device from the admin console, [Tailscale CLI](https://tailscale.com/docs/reference/tailscale-cli), or the [Tailscale API](https://tailscale.com/docs/reference/tailscale-api), the device's key expiry will not change unless you re-authenticate. After you re-authenticate, Tailscale disables the device's key expiry.\r\n\r\nYou can enable or disable key expiry on a device from the [Machines](https://login.tailscale.com/admin/machines) page of the admin console or by using the Tailscale API.\r\n\r\n## [Tags in the Tailscale ecosystem](https://tailscale.com/docs/features/tags\\#tags-in-the-tailscale-ecosystem)\r\n\r\nLike many aspects of a tailnet, you can define and manage tags in the tailnet policy file. While limitations prevent you from using them to authenticate end-user devices, they work seamlessly with nearly every other Tailscale feature, including exit nodes, subnet routers, app connectors, access control lists, and grants.\r\n\r\n### [Exit nodes](https://tailscale.com/docs/features/tags\\#exit-nodes)\r\n\r\nUsing a device as an [exit node](https://tailscale.com/docs/features/exit-nodes) means that other tailnet devices can choose to route all their internet traffic through that device. Routing all traffic through an exit node lets you encrypt internet traffic and access internal networks. For example, you could run a device as an exit node in a corporate office. That way, employees can access the corporate office's internal network when they use that exit node. Although end-user devices can function as exit nodes, it's more common for exit nodes to use a tag-based identity.\r\n\r\n### [Subnet routers](https://tailscale.com/docs/features/tags\\#subnet-routers)\r\n\r\nA [subnet router](https://tailscale.com/docs/features/subnet-routers) is a tailnet device you use to advertise subnet routes to the rest of your tailnet. They're a great way to add entire subnets to your tailnet without installing the Tailscale client to any of the devices (except the subnet router). Although end-user devices can function as subnet routers, it's more common for subnet routers to use a tag-based identity.\r\n\r\n### [App connectors](https://tailscale.com/docs/features/tags\\#app-connectors)\r\n\r\nAn [app connector](https://tailscale.com/docs/features/app-connectors) is a device that routes app-specific traffic in your tailnet. A device running as an app connector is strictly a service-based device. As a result, you must use a tag-based identity to authenticate a device you plan to use as an app connector.\r\n\r\n### [Access controls](https://tailscale.com/docs/features/tags\\#access-controls)\r\n\r\nYou can use tags to select and target service-based devices in your tailnet to create access control policies using ACLs and grants. Because Tailscale can identify tagged devices by any one of their assigned tags, the access control policies that apply to a device with many tags could become complex. As a result, it's best practice to maintain clear documentation of how you leverage and manage tags in your tailnet.\r\n\r\n#### [ACLs](https://tailscale.com/docs/features/tags\\#acls)\r\n\r\nYou can use tags as part of [access control lists (ACLs)](https://tailscale.com/docs/features/access-control/acls) to make it easier to manage which types of devices should be able to communicate. For example, you might use a tag named `tag:prod` for production servers and production databases, then allow all devices with the `tag:prod` tag to communicate with each other.\r\n\r\nThe following example [tailnet policy file](https://tailscale.com/docs/reference/glossary#tailnet-policy-file) lets all devices tagged `tag:prod` communicate with each other.\r\n\r\n```json\r\n{\r\n \"acls\": [\\\r\n {\\\r\n \"action\": \"accept\",\\\r\n \"src\": [\"tag:prod\"],\\\r\n \"dst\": [\"tag:prod:*\"],\\\r\n },\\\r\n ],\r\n}\r\n```\r\n\r\nYou can use the [visual policy editor](https://tailscale.com/docs/features/visual-editor) to manage your tailnet policy file. Refer to the [visual editor reference](https://tailscale.com/docs/reference/visual-editor) for guidance on using the visual editor.\r\n\r\nYou can also ensure that the ACLs for your tagged devices work as expected with [tests](https://tailscale.com/docs/reference/syntax/policy-file#tests), which verify your tailnet policy file before saving and applying it.\r\n\r\nFor example, to verify that your tailnet policy file lets users in the `tag:sre` group to access devices tagged `tag:prod`, you might write an ACL like the following example:\r\n\r\n```json\r\n\"tests\": [\\\r\n {\\\r\n \"src\": \"group:sre\",\\\r\n \"accept\": [\"tag:prod:1234\"],\\\r\n },\\\r\n],\r\n```\r\n\r\nYou can use the [visual policy editor](https://tailscale.com/docs/features/visual-editor) to manage your tailnet policy file. Refer to the [visual editor reference](https://tailscale.com/docs/reference/visual-editor) for guidance on using the visual editor.\r\n\r\n#### [Grants](https://tailscale.com/docs/features/tags\\#grants)\r\n\r\nLike ACLs, you can use tags in grants to target a group of tagged devices. The following example grants devices with the `tag:prod` tag access to devices with the `tag:tailsql` tag.\r\n\r\n```json\r\n{\r\n \"grants\": [\\\r\n {\\\r\n \"src\": [\"tag:prod\"],\\\r\n \"dst\": [\"tag:tailsql\"],\\\r\n \"ip\": [\"*\"]\\\r\n }\\\r\n ]\r\n}\r\n```\r\n\r\nYou can use the [visual policy editor](https://tailscale.com/docs/features/visual-editor) to manage your tailnet policy file. Refer to the [visual editor reference](https://tailscale.com/docs/reference/visual-editor) for guidance on using the visual editor.\r\n\r\n### [Autogroups](https://tailscale.com/docs/features/tags\\#autogroups)\r\n\r\n[Autogroups](https://tailscale.com/docs/reference/targets-and-selectors) are pre-defined groups of devices in your tailnet that would be difficult to create as custom groups. One of these autogroups is `autogroup:tagged`, which selects all devices with a tag-based identity.\r\n\r\nYou cannot use `autogroup:tagged` to define an IP set or a custom group.\r\n\r\n## [Advanced tag hierarchies](https://tailscale.com/docs/features/tags\\#advanced-tag-hierarchies)\r\n\r\nDesignating tag owners is flexible by design. You can assign as many tag owners as you need to a device, and these tag owners can be users, groups, or other tags. Because you can assign a tag as an owner of another tag, it's possible to create complex hierarchies of tag ownership. As a result, it's best practice to maintain clear documentation of how you use tags and to audit tags using tools such as [access control policy tests](https://tailscale.com/docs/reference/syntax/policy-file#tests).\r\n\r\n## [Best practices](https://tailscale.com/docs/features/tags\\#best-practices)\r\n\r\nTo leverage tags effectively, consider the following best practices:\r\n\r\n- **Define clear naming conventions for tags**. Ideally, tag names should follow a consistent and descriptive pattern throughout your tailnet. Defining and enforcing a naming convention early on reduces the likelihood of problems such as ambiguous tag names later on. For example, a tag named \"foo-bar\" doesn't tell you anything about what the tag is intended for, but a tag name \"prod-postgresql-server\" tells you that the tag is for PostgreSQL servers in a production environment. However, even with descriptive names, it's a good idea to document your organization's tag conventions.\r\n- **Use auth keys**. By using [auth keys](https://tailscale.com/docs/features/access-control/auth-keys) with pre-assigned tags, you can streamline the process of authenticating and approving tagged devices.\r\n- **Don't use tags to authenticate user-owned devices**. Tags are intended to authenticate servers and devices that provide a service, which means they have qualities that make them unsuitable for end-user devices, such as a MacBook or an Android phone. Additionally, a device cannot simultaneously use tag-based and user-based identities. Adding a tag to a previously user-authenticated device removes the user's identity.\r\n- **Carefully consider each tag's owners**. Tags are defined by their owners in the `tagOwners` section of the tailnet policy file. Because of their flexibility and the ability for a tag to own another tag, tags can take on [complex ownership hierarchies](https://tailscale.com/docs/features/tags#advanced-tag-hierarchies).\r\n\r\n### [Common patterns for tag names](https://tailscale.com/docs/features/tags\\#common-patterns-for-tag-names)\r\n\r\nTags let you reflect access patterns and network segments based on your organization's requirements. These access patterns and network segments usually fall into a few common categories. Use consistent patterns for tag names based on these categories to make your access control policies easier to understand and maintain over time. Some common categories of access to consider in your tag names are:\r\n\r\n- **Server role**: for example, application server, database, or queue.\r\n- **Application name**: for example, support console, finance reporting, or operations dashboard.\r\n- **Environment**: for example, production, staging, or development\r\n- **Location**: for example, Americas, EMEA, South Asia.\r\n\r\nWhile a device can have many tags assigned to it, tags are not \"joined\" for access rules. For example, you cannot define a rule that permits access to devices with both `tag:prod` and `tag:database`. Instead, you can use a composite tag such as `tag:prod-database` to represent this type of segmented access pattern. Below are some examples of composite tags.\r\n\r\n| **Tag** | **Access control** |\r\n| --- | --- |\r\n| `tag:prod-app` | To production application servers |\r\n| `tag:nonprod-db` | To non-production database servers |\r\n| `tag:prod-app-finance-reporting` | To the production finance reporting application |\r\n| `tag:prod-emea-app-support-console` | To the production support console application in EMEA |\r\n| `tag:prod-asiasouth-ingest-logging` | To the production logging ingest endpoint in South Asia. |\r\n\r\n## [Working with tags](https://tailscale.com/docs/features/tags\\#working-with-tags)\r\n\r\nUse the following sections to find more information about working with tags:\r\n\r\n- [Define a tag](https://tailscale.com/docs/features/tags#define-a-tag).\r\n- [Define tag owners](https://tailscale.com/docs/features/tags#define-tag-owners).\r\n- [Apply tags to a device](https://tailscale.com/docs/features/tags#apply-a-tag-to-a-device).\r\n- [Apply a tag from another tag](https://tailscale.com/docs/features/tags#apply-a-tag-from-another-tag).\r\n\r\n### [Define a tag](https://tailscale.com/docs/features/tags\\#define-a-tag)\r\n\r\nBefore assigning a tag to a device, you must create the tag in the [tailnet policy file](https://tailscale.com/docs/reference/syntax/policy-file) and define who can use that tag to authenticate devices. You create a tag by defining it in the [`tagOwners`](https://tailscale.com/docs/reference/syntax/policy-file#tag-owners) section of the tailnet policy file.\r\n\r\nThe following example creates the tag `tag:server` and assigns `dave@example.com` as the sole owner. Only the tag owner can apply the tag.\r\n\r\n```json\r\n{\r\n \"tagOwners\": {\r\n \"tag:server\": [\"dave@example.com\"], // dave@example.com can authenticate devices with the tag:server tag\r\n }\r\n}\r\n```\r\n\r\nYou can use the [visual policy editor](https://tailscale.com/docs/features/visual-editor) to manage your tailnet policy file. Refer to the [visual editor reference](https://tailscale.com/docs/reference/visual-editor) for guidance on using the visual editor.\r\n\r\nTailscale ignores tag name case and parses all tags in the tailnet policy file as lowercase.\r\n\r\n### [Define tag owners](https://tailscale.com/docs/features/tags\\#define-tag-owners)\r\n\r\nYou must explicitly define who can use a tag to grant its permissions on a device. You can define tag owners in the [`tagOwners`](https://tailscale.com/docs/reference/syntax/policy-file#tag-owners) section of the tailnet policy file.\r\n\r\nA tag can also have an empty list of owners in the tailnet policy file. All tags are implicitly owned by [Owners, Admins, and Network admins](https://tailscale.com/docs/reference/user-roles) of a tailnet. You can apply these tags to devices from the admin console and as part of an [auth key](https://tailscale.com/docs/features/access-control/auth-keys).\r\n\r\nThe following example shows the `tag:infrastructure` with no tag owners.\r\n\r\n```json\r\n{\r\n \"tagOwners\": {\r\n \"tag:server\": [\"dave@tailscale.com\"],\r\n \"tag:infrastructure\": [], // No tag owners defined\r\n }\r\n}\r\n```\r\n\r\nYou can use the [visual policy editor](https://tailscale.com/docs/features/visual-editor) to manage your tailnet policy file. Refer to the [visual editor reference](https://tailscale.com/docs/reference/visual-editor) for guidance on using the visual editor.\r\n\r\n### [Apply a tag to a device](https://tailscale.com/docs/features/tags\\#apply-a-tag-to-a-device)\r\n\r\nYou can tag devices using the admin console, the [Tailscale CLI](https://tailscale.com/docs/reference/tailscale-cli), or the Tailscale API.\r\n\r\nWhen you re-authenticate and tag a device, it generates a new [node key](https://tailscale.com/docs/concepts/node-keys) for the device. The [Tailscale IP address](https://tailscale.com/docs/concepts/tailscale-ip-addresses) for the device does not change.\r\n\r\n#### [Apply a tag to a device in the admin console](https://tailscale.com/docs/features/tags\\#apply-a-tag-to-a-device-in-the-admin-console)\r\n\r\nYou must be an [Owner, Admin, or Network admin](https://tailscale.com/docs/reference/user-roles) of a tailnet to tag a device from the [admin console](https://login.tailscale.com/admin). You don't need to re-authenticate because the current user is automatically used to authenticate the device.\r\n\r\nTo tag a device from the admin console:\r\n\r\n1. Open the [Machines](https://login.tailscale.com/admin/machines) page in the admin console.\r\n2. Find the row corresponding to the device you are interested in.\r\n3. Select on the ![ellipsis icon](https://tailscale.com/files/images/icons/fa-ellipsis-h.svg) menu at the far right, then select the **Edit tags** option.\r\n4. Add, change, or remove desired tags. To apply a tag, it must already exist in the [tailnet policy file](https://tailscale.com/docs/reference/glossary#tailnet-policy-file).\r\n5. Select **Save** to apply tags.\r\n\r\n[Owners, Admins, and Network admins](https://tailscale.com/docs/reference/user-roles) can apply any tag from the admin console even if they don't own the tag.\r\n\r\nYou cannot remove all tags from a tagged device in the admin console because the device must have an identity. Either assign the device a new tag or re-authenticate to Tailscale from the device.\r\n\r\n#### [Apply a tag to a device with the CLI](https://tailscale.com/docs/features/tags\\#apply-a-tag-to-a-device-with-the-cli)\r\n\r\nYou can use the [Tailscale CLI](https://tailscale.com/docs/reference/tailscale-cli) to add and remove tags from devices running Linux, macOS, or Windows. To tag other devices, use the admin console.\r\n\r\nTo assign tags to a device using the CLI, run `tailscale login` command with the `--advertise-tags=tag:` flag.\r\n\r\n```shell\r\nsudo tailscale login --advertise-tags=tag:server\r\n```\r\n\r\nTo assign multiple tags to a device, pass multiple tags (separated with commas) to the `--advertise-tags` flag.\r\n\r\n```shell\r\nsudo tailscale login --advertise-tags=tag:server,tag:development\r\n```\r\n\r\nTo remove all tags from a device, use the `--advertise-tags=` flag without any values.\r\n\r\n```shell\r\nsudo tailscale login --advertise-tags=\r\n```\r\n\r\nYou cannot remove tags using the `--advertise-tags` flag if the device uses an auth key. Instead, generate a new auth key with the new set of tags.\r\n\r\nYou might need to change the signed-in user on the device if it's already authenticated with another user. To re-authenticate with the current user, add the `--force-reauth` flag to the `tailscale up` command:\r\n\r\n```shell\r\nsudo tailscale up --advertise-tags=tag:server --force-reauth\r\n```\r\n\r\n#### [Apply a tag to a device using the API](https://tailscale.com/docs/features/tags\\#apply-a-tag-to-a-device-using-the-api)\r\n\r\nYou can apply a tag to a device using the [Update device tags](https://tailscale.com/api#tag/devices/POST/device/%7BdeviceId%7D/tags) method from the [Tailscale API](https://tailscale.com/docs/reference/tailscale-api).\r\n\r\nTo apply a tag this way, send a `POST` request for a device, with the body specifying the desired `tags`. For example:\r\n\r\n```shell\r\ncurl https://api.tailscale.com/api/v2/device/11055/tags \\\r\n-u \"tskey-\" \\\r\n-H \"Content-Type: application/json\" \\\r\n--data-binary '{\"tags\": [\"tag:foo\", \"tag:bar\"]}'\r\n```\r\n\r\n### [Apply a tag from another tag](https://tailscale.com/docs/features/tags\\#apply-a-tag-from-another-tag)\r\n\r\nYou can apply different tags from those in the [auth key](https://tailscale.com/docs/features/access-control/auth-keys) when you authenticate. However, doing so replaces the device's existing tags.\r\n\r\n**Important for OAuth authentication**: When an OAuth client or auth key assigns tags to a device, the requested tags must either exactly match the full set of tags on the OAuth client or auth key, or each requested tag must be owned by one of the authenticating entity's tags as defined in the `tagOwners` section. The exact-match check does not consult `tagOwners`—it merely verifies the requested tags are identical to the authenticating tags. For any other combination, including applying a subset of tags, ownership must be explicitly configured in `tagOwners`.\r\n\r\nApplying a tag from another tag is useful for larger infrastructure deployments, where you might need to tag many servers, typically using a deployment tool. For example, you could have your deployment system tagged with `tag:deployment-1`, which owns both `tag:prod-2` and `tag:test-2`:\r\n\r\n```json\r\n \"TagOwners\": {\r\n \"tag:deployment-1\": [\"alice@tailscale.com\"],\r\n \"tag:prod-2\": [\"tag:deployment-1\"],\r\n \"tag:test-2\": [\"tag:deployment-1\"],\r\n },\r\n```\r\n\r\nYou can use the [visual policy editor](https://tailscale.com/docs/features/visual-editor) to manage your tailnet policy file. Refer to the [visual editor reference](https://tailscale.com/docs/reference/visual-editor) for guidance on using the visual editor.\r\n\r\nIn this configuration, an OAuth client with `tag:deployment-1` can apply either `tag:prod-2` or `tag:test-2` to devices. An OAuth client whose only tag is `tag:prod-2` can also apply `tag:prod-2`, since the tags are an exact match. However, if an OAuth client holds multiple tags and needs to apply only a subset of them, each requested tag must be owned by one of the authenticating tags. To support this, add the tag as its own owner:\r\n\r\n```json\r\n \"TagOwners\": {\r\n \"tag:deployment-1\": [\"alice@tailscale.com\"],\r\n \"tag:prod-2\": [\"tag:deployment-1\", \"tag:prod-2\"],\r\n \"tag:test-2\": [\"tag:deployment-1\", \"tag:test-2\"],\r\n },\r\n```\r\n\r\nYou can use the [visual policy editor](https://tailscale.com/docs/features/visual-editor) to manage your tailnet policy file. Refer to the [visual editor reference](https://tailscale.com/docs/reference/visual-editor) for guidance on using the visual editor.\r\n\r\nYou could generate an [auth key](https://tailscale.com/docs/features/access-control/auth-keys)`` with the tag `tag:deployment-1`, and make it available to the deployment tool. Then, depending on what workload you deploy, the system authenticates the device and applies the correct infrastructure tag, which enforces the correct [access controls](https://tailscale.com/docs/features/access-control). When spinning up a new production server, the deployment tool could tag the device as `tag:prod-2`:\r\n\r\n```shell\r\nsudo tailscale up --auth-key= --advertise-tags=tag:prod-2\r\n```\r\n\r\n![Project Logo](https://cdn.brandfetch.io/tailscale.com/fallback/lettermark/theme/dark/h/256/w/256/icon?c=1bfwsmEH20zzEfSNTed)\r\n\r\nAsk AI\r\n\r\nreCAPTCHA\r\n\r\nRecaptcha requires verification.\r\n\r\nprotected by **reCAPTCHA**\r\n","html":"

Group devices with tags

\n

Last validated: Dec 4, 2025

\n

Tagsare available for all plans.

\n

All plans include 50 tagged devices. If you need more than 50 tagged devices, contact our Sales team.

\n

Tailscale tags are how you authenticate and identify non-user devices, such as servers and ephemeral nodes. They serve two primary purposes: to provide an identity to non-user devices and to let you manage access control policies based on purpose. In this context, a purpose could be anything from hosting a web server to serving as a subnet router for employees in a specific geographic location.

\n

Tags are essentially service accounts, but with more flexibility⎯you can assign multiple tags to a device to account for multiple purposes. For example, you might have a device that runs a PostgreSQL database and serves as a web server for internal access. In such a scenario, you could assign the device the following tags (each of which you could target individually using access control policies): tag:postgresql, tag:internal-access, and tag:web-server.

\n

Other key characteristics of tags include:

\n
    \n
  • Applying a tag to a device removes any user-based authentication.
    • \n
  • Each non-user device can have as many tags as you need.
    • \n
  • Tags are defined in the tailnet policy file in the tagOwners section.
    • \n
  • Only designated tag owners can apply tags to devices; each tag can have as many owners as necessary.
    • \n
\n

Requirements

\n

Tags are a free feature and are available for all pricing plans. However, you must have permission to perform some tag-related operations:

\n\n

Limitations

\n

Tags have the following limitations and restrictions:

\n
    \n
  • You cannot remove all tags from a device. A device with a tag-based identity must have at least one tag.
    • \n
  • You cannot remove tags using the --advertise-tags flag if the device uses an auth key. Instead, generate a new auth key with the latest set of tags.
    • \n
  • IP sets do not support tags.
    • \n
  • Devices with a tag-based identity can only SSH into other tagged devices; they cannot SSH into devices with a user-based identity.
    • \n
  • Some restrictions exist around using tags to define a group or as the SSH source.
    • \n
\n

Use cases

\n

Tags are ideal for managing devices you don't want to link to a specific user (such as a server hosting a web application) because removing a user also removes all their devices. If you link a service-providing device to a user, you lose that device if you remove the user. Removing a user won't affect the device if you use tags to manage the device instead. Do not use tags to associate a user device with a user account. Tags are not designed to tie individual users to a device. They're intended to manage devices with service account roles. Using tags as a substitute for users poses a security risk because the user's devices will remain on your network even if you remove the user.

\n

Tags provide a way to allow multiple users to manage a device. When you manage devices with users, you must link each device to a single user, which isn't ideal for devices that host shared resources. However, when you manage devices with tags, you can assign one or more users as tag owners with tags. These users can manage all the devices with the tags they own.

\n

Warnings about tags

\n

Only use tags for non-human machines. Users can only access and use Tailscale through their designated user accounts. Using tags to annotate user devices is poor practice because a device cannot simultaneously have a user and a tag. Adding a tag to a device removes the associated user. Devices can have tags or a user account, not both.

\n

Use tags to:

\n
    \n
  • Manage devices you don't have tied to a specific user (such as a server hosting a web application).
    • \n
  • Manage devices you want to allow multiple users to manage.
    • \n
\n

Do not use tags to:

\n
    \n
  • Annotate user devices.
    • \n
  • Link a user device with a user.
    • \n
  • Authenticate end-user devices, such as laptops or mobile devices.
    • \n
\n

Ownership

\n

There's no \"tag\" section of the tailnet policy file. Instead, you define tags by their owners in the tagOwners section of the tailnet policy file. Only owners of a tag can apply that tag to devices in your Tailscale network (known as a tailnet). Tag owners can be users, groups, or even other tags, which means you can create complex tag ownership hierarchies.

\n

A tagged device's identity is the combination of all its tags (not the intersection). You can assign any number of tags to a device and manage the permissions for each tag separately. For example, if you have a device with the tags tag:postgresql, tag:prod, and tag:ci-cd, an access control policy for any one of these tags would apply to the device.

\n

Owner, Admin, or Network admin can apply any tag, even if they aren't tag owners.

\n

Tag vs. user authentication

\n

Tags are parallel to user authentication. They serve the same role as a user account, except they're intended for service-based devices, such as a web server or an app connector. As a result, it's impossible for a user account identity and a tag identity to exist on the same device. Applying a tag to a device previously authenticated with a user account removes the user account. Similarly, authenticating a device with a user account removes all tags from the device.

\n

Because tags are for non-user devices, they have qualities and limitations that make them unsuitable for authenticating end-user devices, such as a MacBook or a mobile device. For example, devices with a tag-based identity cannot use SSH to connect to a device with a user-based identity.

\n

Key expiry

\n

When you apply a tag to a device for the first time and authenticate it, the tagged device's key expiry is disabled by default.

\n

If you re-authenticate a device tagged before March 10, 2022, its expiry will be disabled by default.

\n

If you change the tags on the device from the admin console, Tailscale CLI, or the Tailscale API, the device's key expiry will not change unless you re-authenticate. After you re-authenticate, Tailscale disables the device's key expiry.

\n

You can enable or disable key expiry on a device from the Machines page of the admin console or by using the Tailscale API.

\n

Tags in the Tailscale ecosystem

\n

Like many aspects of a tailnet, you can define and manage tags in the tailnet policy file. While limitations prevent you from using them to authenticate end-user devices, they work seamlessly with nearly every other Tailscale feature, including exit nodes, subnet routers, app connectors, access control lists, and grants.

\n

Exit nodes

\n

Using a device as an exit node means that other tailnet devices can choose to route all their internet traffic through that device. Routing all traffic through an exit node lets you encrypt internet traffic and access internal networks. For example, you could run a device as an exit node in a corporate office. That way, employees can access the corporate office's internal network when they use that exit node. Although end-user devices can function as exit nodes, it's more common for exit nodes to use a tag-based identity.

\n

Subnet routers

\n

A subnet router is a tailnet device you use to advertise subnet routes to the rest of your tailnet. They're a great way to add entire subnets to your tailnet without installing the Tailscale client to any of the devices (except the subnet router). Although end-user devices can function as subnet routers, it's more common for subnet routers to use a tag-based identity.

\n

App connectors

\n

An app connector is a device that routes app-specific traffic in your tailnet. A device running as an app connector is strictly a service-based device. As a result, you must use a tag-based identity to authenticate a device you plan to use as an app connector.

\n

Access controls

\n

You can use tags to select and target service-based devices in your tailnet to create access control policies using ACLs and grants. Because Tailscale can identify tagged devices by any one of their assigned tags, the access control policies that apply to a device with many tags could become complex. As a result, it's best practice to maintain clear documentation of how you leverage and manage tags in your tailnet.

\n

ACLs

\n

You can use tags as part of access control lists (ACLs) to make it easier to manage which types of devices should be able to communicate. For example, you might use a tag named tag:prod for production servers and production databases, then allow all devices with the tag:prod tag to communicate with each other.

\n

The following example tailnet policy file lets all devices tagged tag:prod communicate with each other.

\n
{\r\n  \"acls\": [\\\r\n    {\\\r\n      \"action\": \"accept\",\\\r\n      \"src\": [\"tag:prod\"],\\\r\n      \"dst\": [\"tag:prod:*\"],\\\r\n    },\\\r\n  ],\r\n}\n
\n

You can use the visual policy editor to manage your tailnet policy file. Refer to the visual editor reference for guidance on using the visual editor.

\n

You can also ensure that the ACLs for your tagged devices work as expected with tests, which verify your tailnet policy file before saving and applying it.

\n

For example, to verify that your tailnet policy file lets users in the tag:sre group to access devices tagged tag:prod, you might write an ACL like the following example:

\n
\"tests\": [\\\r\n  {\\\r\n    \"src\": \"group:sre\",\\\r\n    \"accept\": [\"tag:prod:1234\"],\\\r\n  },\\\r\n],\n
\n

You can use the visual policy editor to manage your tailnet policy file. Refer to the visual editor reference for guidance on using the visual editor.

\n

Grants

\n

Like ACLs, you can use tags in grants to target a group of tagged devices. The following example grants devices with the tag:prod tag access to devices with the tag:tailsql tag.

\n
{\r\n  \"grants\": [\\\r\n    {\\\r\n      \"src\": [\"tag:prod\"],\\\r\n      \"dst\": [\"tag:tailsql\"],\\\r\n      \"ip\": [\"*\"]\\\r\n    }\\\r\n  ]\r\n}\n
\n

You can use the visual policy editor to manage your tailnet policy file. Refer to the visual editor reference for guidance on using the visual editor.

\n

Autogroups

\n

Autogroups are pre-defined groups of devices in your tailnet that would be difficult to create as custom groups. One of these autogroups is autogroup:tagged, which selects all devices with a tag-based identity.

\n

You cannot use autogroup:tagged to define an IP set or a custom group.

\n

Advanced tag hierarchies

\n

Designating tag owners is flexible by design. You can assign as many tag owners as you need to a device, and these tag owners can be users, groups, or other tags. Because you can assign a tag as an owner of another tag, it's possible to create complex hierarchies of tag ownership. As a result, it's best practice to maintain clear documentation of how you use tags and to audit tags using tools such as access control policy tests.

\n

Best practices

\n

To leverage tags effectively, consider the following best practices:

\n
    \n
  • Define clear naming conventions for tags. Ideally, tag names should follow a consistent and descriptive pattern throughout your tailnet. Defining and enforcing a naming convention early on reduces the likelihood of problems such as ambiguous tag names later on. For example, a tag named \"foo-bar\" doesn't tell you anything about what the tag is intended for, but a tag name \"prod-postgresql-server\" tells you that the tag is for PostgreSQL servers in a production environment. However, even with descriptive names, it's a good idea to document your organization's tag conventions.
    • \n
  • Use auth keys. By using auth keys with pre-assigned tags, you can streamline the process of authenticating and approving tagged devices.
    • \n
  • Don't use tags to authenticate user-owned devices. Tags are intended to authenticate servers and devices that provide a service, which means they have qualities that make them unsuitable for end-user devices, such as a MacBook or an Android phone. Additionally, a device cannot simultaneously use tag-based and user-based identities. Adding a tag to a previously user-authenticated device removes the user's identity.
    • \n
  • Carefully consider each tag's owners. Tags are defined by their owners in the tagOwners section of the tailnet policy file. Because of their flexibility and the ability for a tag to own another tag, tags can take on complex ownership hierarchies.
    • \n
\n

Common patterns for tag names

\n

Tags let you reflect access patterns and network segments based on your organization's requirements. These access patterns and network segments usually fall into a few common categories. Use consistent patterns for tag names based on these categories to make your access control policies easier to understand and maintain over time. Some common categories of access to consider in your tag names are:

\n
    \n
  • Server role: for example, application server, database, or queue.
    • \n
  • Application name: for example, support console, finance reporting, or operations dashboard.
    • \n
  • Environment: for example, production, staging, or development
    • \n
  • Location: for example, Americas, EMEA, South Asia.
    • \n
\n

While a device can have many tags assigned to it, tags are not \"joined\" for access rules. For example, you cannot define a rule that permits access to devices with both tag:prod and tag:database. Instead, you can use a composite tag such as tag:prod-database to represent this type of segmented access pattern. Below are some examples of composite tags.

\n

| Tag | Access control |\r\n| --- | --- |\r\n| tag:prod-app | To production application servers |\r\n| tag:nonprod-db | To non-production database servers |\r\n| tag:prod-app-finance-reporting | To the production finance reporting application |\r\n| tag:prod-emea-app-support-console | To the production support console application in EMEA |\r\n| tag:prod-asiasouth-ingest-logging | To the production logging ingest endpoint in South Asia. |

\n

Working with tags

\n

Use the following sections to find more information about working with tags:

\n\n

Define a tag

\n

Before assigning a tag to a device, you must create the tag in the tailnet policy file and define who can use that tag to authenticate devices. You create a tag by defining it in the tagOwners section of the tailnet policy file.

\n

The following example creates the tag tag:server and assigns dave@example.com as the sole owner. Only the tag owner can apply the tag.

\n
{\r\n  \"tagOwners\": {\r\n    \"tag:server\": [\"dave@example.com\"], // dave@example.com can authenticate devices with the tag:server tag\r\n  }\r\n}\n
\n

You can use the visual policy editor to manage your tailnet policy file. Refer to the visual editor reference for guidance on using the visual editor.

\n

Tailscale ignores tag name case and parses all tags in the tailnet policy file as lowercase.

\n

Define tag owners

\n

You must explicitly define who can use a tag to grant its permissions on a device. You can define tag owners in the tagOwners section of the tailnet policy file.

\n

A tag can also have an empty list of owners in the tailnet policy file. All tags are implicitly owned by Owners, Admins, and Network admins of a tailnet. You can apply these tags to devices from the admin console and as part of an auth key.

\n

The following example shows the tag:infrastructure with no tag owners.

\n
{\r\n  \"tagOwners\": {\r\n    \"tag:server\": [\"dave@tailscale.com\"],\r\n    \"tag:infrastructure\": [], // No tag owners defined\r\n  }\r\n}\n
\n

You can use the visual policy editor to manage your tailnet policy file. Refer to the visual editor reference for guidance on using the visual editor.

\n

Apply a tag to a device

\n

You can tag devices using the admin console, the Tailscale CLI, or the Tailscale API.

\n

When you re-authenticate and tag a device, it generates a new node key for the device. The Tailscale IP address for the device does not change.

\n

Apply a tag to a device in the admin console

\n

You must be an Owner, Admin, or Network admin of a tailnet to tag a device from the admin console. You don't need to re-authenticate because the current user is automatically used to authenticate the device.

\n

To tag a device from the admin console:

\n
    \n
  1. Open the Machines page in the admin console.
    2. \n
  2. Find the row corresponding to the device you are interested in.
    3. \n
  3. Select on the \"ellipsis menu at the far right, then select the Edit tags option.
    4. \n
  4. Add, change, or remove desired tags. To apply a tag, it must already exist in the tailnet policy file.
    5. \n
  5. Select Save to apply tags.
    6. \n
\n

Owners, Admins, and Network admins can apply any tag from the admin console even if they don't own the tag.

\n

You cannot remove all tags from a tagged device in the admin console because the device must have an identity. Either assign the device a new tag or re-authenticate to Tailscale from the device.

\n

Apply a tag to a device with the CLI

\n

You can use the Tailscale CLI to add and remove tags from devices running Linux, macOS, or Windows. To tag other devices, use the admin console.

\n

To assign tags to a device using the CLI, run tailscale login command with the --advertise-tags=tag:<tag-name> flag.

\n
sudo tailscale login --advertise-tags=tag:server\n
\n

To assign multiple tags to a device, pass multiple tags (separated with commas) to the --advertise-tags flag.

\n
sudo tailscale login --advertise-tags=tag:server,tag:development\n
\n

To remove all tags from a device, use the --advertise-tags= flag without any values.

\n
sudo tailscale login --advertise-tags=\n
\n

You cannot remove tags using the --advertise-tags flag if the device uses an auth key. Instead, generate a new auth key with the new set of tags.

\n

You might need to change the signed-in user on the device if it's already authenticated with another user. To re-authenticate with the current user, add the --force-reauth flag to the tailscale up command:

\n
sudo tailscale up --advertise-tags=tag:server --force-reauth\n
\n

Apply a tag to a device using the API

\n

You can apply a tag to a device using the Update device tags method from the Tailscale API.

\n

To apply a tag this way, send a POST request for a device, with the body specifying the desired tags. For example:

\n
curl https://api.tailscale.com/api/v2/device/11055/tags \\\r\n-u \"tskey-<key>\" \\\r\n-H \"Content-Type: application/json\" \\\r\n--data-binary '{\"tags\": [\"tag:foo\", \"tag:bar\"]}'\n
\n

Apply a tag from another tag

\n

You can apply different tags from those in the auth key when you authenticate. However, doing so replaces the device's existing tags.

\n

Important for OAuth authentication: When an OAuth client or auth key assigns tags to a device, the requested tags must either exactly match the full set of tags on the OAuth client or auth key, or each requested tag must be owned by one of the authenticating entity's tags as defined in the tagOwners section. The exact-match check does not consult tagOwners—it merely verifies the requested tags are identical to the authenticating tags. For any other combination, including applying a subset of tags, ownership must be explicitly configured in tagOwners.

\n

Applying a tag from another tag is useful for larger infrastructure deployments, where you might need to tag many servers, typically using a deployment tool. For example, you could have your deployment system tagged with tag:deployment-1, which owns both tag:prod-2 and tag:test-2:

\n
  \"TagOwners\": {\r\n    \"tag:deployment-1\": [\"alice@tailscale.com\"],\r\n    \"tag:prod-2\": [\"tag:deployment-1\"],\r\n    \"tag:test-2\": [\"tag:deployment-1\"],\r\n  },\n
\n

You can use the visual policy editor to manage your tailnet policy file. Refer to the visual editor reference for guidance on using the visual editor.

\n

In this configuration, an OAuth client with tag:deployment-1 can apply either tag:prod-2 or tag:test-2 to devices. An OAuth client whose only tag is tag:prod-2 can also apply tag:prod-2, since the tags are an exact match. However, if an OAuth client holds multiple tags and needs to apply only a subset of them, each requested tag must be owned by one of the authenticating tags. To support this, add the tag as its own owner:

\n
  \"TagOwners\": {\r\n    \"tag:deployment-1\": [\"alice@tailscale.com\"],\r\n    \"tag:prod-2\": [\"tag:deployment-1\", \"tag:prod-2\"],\r\n    \"tag:test-2\": [\"tag:deployment-1\", \"tag:test-2\"],\r\n  },\n
\n

You can use the visual policy editor to manage your tailnet policy file. Refer to the visual editor reference for guidance on using the visual editor.

\n

You could generate an auth key<key-1> with the tag tag:deployment-1, and make it available to the deployment tool. Then, depending on what workload you deploy, the system authenticates the device and applies the correct infrastructure tag, which enforces the correct access controls. When spinning up a new production server, the deployment tool could tag the device as tag:prod-2:

\n
sudo tailscale up --auth-key=<key-1> --advertise-tags=tag:prod-2\n
\n

\"Project

\n

Ask AI

\n

reCAPTCHA

\n

Recaptcha requires verification.

\n

protected by reCAPTCHA

\n"}