Enrollment keys

An enrollment key lets a device join your TxNet without anyone signing in on it in a browser. Use one for servers, virtual machines, CI runners and anything else that runs unattended. You create the key in the dashboard, then pass it to the device once when it joins.

How it works#

• A device that joins with a key belongs to the key’s owner. That is the person who created it, unless an admin picked someone else.
• If the key has tags, every device that joins with it gets those tags. Your access policy can then give the devices access by tag.
• Devices that join with a tagged key never have to sign in again. Devices that join with an untagged key expire after 180 days, just like devices where someone signed in. See Key expiry.
• A key is only used when a device joins. Deleting the key later does not disconnect devices that already joined with it.

Types of keys#

Keys expire automatically. An ordinary key lasts 90 days and an organization-owned key lasts one year. The Expires column in the key list shows when.

Create a key#

Admins and owners manage every key in the TxNet under Settings → Enrollment keys. Members can create keys for their own devices under My settings → My enrollment keys. The Add Device button on the Machines page takes you to the right place.

1. Click Create Key.
2. Enter a Description, for example Web servers or CI runner, so you can tell your keys apart later.
3. Admins only: choose an Owner if the devices should belong to someone other than you. Leave it empty otherwise; the key is then yours.
4. Add Tags if the devices should be tagged. Type a tag such as tag:server and click Add tag. A tag must already be declared in your access policy, and unless you are an admin, you must be one of its owners.
5. Tick Reusable if more than one device will use the key. Tick Ephemeral for temporary machines.
6. Click Create Key. The key and a ready-made command appear under Enrollment key created.
7. Copy the key now and store it somewhere safe, such as your password manager or your deployment tool’s secret store. It is shown only once.

Use a key on a device#

Linux

Install TxHub (see Install the app), then run:

$ sudo txhub up --auth-key=<your enrollment key>

To keep the key out of your shell history and scripts, save it in a file that only root can read and point the command at the file:

$ sudo txhub up --auth-key=file:/etc/txhub/enrollment-key

Windows Server

Use the Windows Server .zip from the download page and set the key before running the install script in an administrator PowerShell:

$env:TXHUB_AUTHKEY = "<your enrollment key>"
.\install-txhub-windows.ps1

The device appears under Machines as soon as it has joined. Run txhub status on it to check.

Organization-owned keys#

An ordinary key stops working when the person who owns it leaves the TxNet. For a fleet that must keep joining new machines no matter who is on the team, admins can create an organization-owned key instead.

1. First create a service account for the fleet: go to Users, click Create User and tick System user (no login). A system user has no password and can never sign in; it only owns keys and devices.
2. Under Settings → Enrollment keys, click Create Key and choose the system user as the Owner.
3. Add at least one tag, tick Reusable, and turn on Organization-owned. Both are required for an organization-owned key.
4. Click Create Key and store the key in your provisioning tool.

Revoke a key#

In the key list, click the bin icon on the key’s row and confirm Delete this enrollment key?. The key stops working at once. You can delete keys you created yourself; admins can delete any key.

Deleting a key does not remove the devices that joined with it. If a key leaked, also check Machines for devices you do not recognise and remove them. See Remove a device.

When a person is removed from the TxNet, their ordinary keys are deleted and their devices expire. Organization-owned keys are kept.

Good to know#

• The key list shows each key’s type, how many times it has been used (Uses), who owns it, and when it was created and expires. Admins can switch on Org-owned only to see just the organization-owned keys.
• Don’t rely on ephemeral devices disappearing from the list by themselves yet. Check Machines now and then and remove the ones you no longer need.
• A device whose key expired can rejoin in place, keeping its name and address, by running txhub up --auth-key=… again with a valid key from the same owner.

Troubleshooting#

If txhub up fails, the message says why:

If creating a key fails with a message about tags, the tag is not declared in your access policy, or you are not one of its owners. See Access policy.