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-approved, for servers. If your tailnet has device approval enabled, this allows you to add a device to your network without further authorization. For example, shared devices, such as servers, should use a pre-approved auth key to connect in a network with device approval.
• Pre-signed, for nodes whose auth keys are signed locally on a signing node, which applies to tailnets with tailnet lock enabled. You can make an auth key (created by any means) pre-signed only by using the tailscale lock sign CLI command.
• 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

You need to be an Owner, Admin, IT admin, or Network admin of a tailnet in order to generate a key.

Step 1: Generate an auth key

Open the Keys page of the admin console. You can choose what kind of key you’d like to generate. You can also choose the number of days, between 1 and 90 inclusive, for the key expiry. The default is 90 days.

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 approval enabled for your network.

The Keys 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 in the tailscale up command to supply the key and bypass interactive login:

sudo tailscale up --authkey tskey-abcdef1432341818

Optional: Revoking a key

You need to be an Owner, Admin, IT admin, or Network admin of a tailnet in order to revoke a key.

You can revoke only your own keys. You cannot see or revoke keys that belong to someone else.

To revoke a key, open 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 page.

Key expiry

An auth key will automatically expire after the number of days you chose when you generated the key. If you want to continue using an auth key after a key expires, you need to generate a new key.

If an auth key expires, any node authorized by it will stay authorized, and expire when the node key expires.

Key expiry for a tagged device is disabled by default. If you change the tags on the device via the admin console, Tailscale CLI, or Tailscale API, the device’s key expiry will not change unless you are asked to re-authenticate. That is, if it is enabled, it stays enabled; and if it is disabled, it stays disabled. Once you re-authenticate, the device’s key expiry will be disabled.

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

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.