Pre-authentication keys (“auth keys” for short) let you register new nodes without needing to sign in via a web browser. This is most useful when spinning up containers, IoT devices, or using infrastructure-as-code systems like Terraform.

About auth keys

Types of auth keys

Auth keys can either be:

• One-off, for one-time use. They can be used to connect a device or server, only once. This is meant for situations where you can’t authenticate on the device yourself, so using a key is more practical. For example, a cloud server might use a one-off key to connect.
• Reusable, for multiple uses. They can be used to connect multiple nodes. For example, multiple instances of on-prem database might use a reusable key to connect.

Depending on what devices you’re authenticating, consider using an auth key that is:

• Ephemeral, for authenticating ephemeral nodes as part of short-lived workloads. Since node keys are not persisted when a workload restarts, these will reconnect as a different node. Nodes which are no longer active will be automatically removed. For example, containers or Lambda functions should use an ephemeral key to connect.
• Pre-authorized, for servers. If your tailnet has device authorization enabled, this allows you to add a device to your network without further authorization. For example, shared devices, such as servers, should use a tagged auth key to connect in a network with device authorization.
• Tagged, for servers. By including an ACL tag in an auth key, devices using the auth key will automatically be tagged. ACLs restricting the device’s permissions based on the tag will apply as soon as the device is provisioned. For example, shared devices, such as servers, should use a tagged auth key to connect.

Authentication

Auth keys authenticate a machine as the user who generated the key. That is, if Alice generates an auth key, and uses it to add a server to her tailnet, then that machine is authenticated with Alice’s identity. Think of it as logging into a machine.

Generating a key

Step 1: Generate an auth key

As a network admin, visit the auth key page. You can choose what kind of key you’d like to generate.

You can generate an auth key that has ACL tags, so that when used, the device’s identity is the tag. You can also generate an auth key that is pre-authorized so it will be automatically approved if you have device authorization enabled for your network.

This page also gives you the ability to revoke existing keys.

Step 2: Register a node with the auth key

When you register a node, use the --authkey option to supply the key and bypass interactive login:

sudo tailscale up --authkey tskey-abcdef1432341818

Optional: Revoking a key

To revoke a key, visit the keys page of the admin console, locate the key in the table at the bottom, and press Revoke. Recently revoked keys are also shown on the page. Note that one-off keys are considered revoked once they are used.

Any nodes authorized with the key will stay authorized, even after the key is revoked. To de-authorize the node, delete it from the machines admin page.

Key expiry

An auth key will automatically expire after 90 days. If you want to continue using an auth key after a key expires, you need to generate a new key.

The keys page of the admin console shows recently expired keys.

Recently revoked or expired keys

Recently revoked or expired keys can be seen on the keys page of the admin console.