Key and secret management

You can set up various types of keys and secrets for securely connecting to resources in your Tailscale network (known as a tailnet). This topic explains the fundamentals of managing each kind of key and secret that we provide.

For more in-depth information on tailnet security, see Best practices to secure your tailnet.

Keys and secrets best practices

Ensure you keep your keys and secrets secure. Make sure to copy your keys and secrets into a password manager as soon as they are generated and displayed. The secrets will only be displayed once in their entirety. If you don't copy it down, you will need to generate a new key or secret.

Make sure you are aware of the key expiry for each key type, and manage them accordingly. System for Cross-domain Identity Management (SCIM) API keys and webhook endpoint secrets do not expire.

We strongly recommend that you use a secrets manager or consult with your cloud provider for directions for securely storing your keys and secrets. Do not store sensitive information such as an OAuth client or API access token in source control.

Key prefixes

Each type of Tailscale-generated key contains a key prefix to help you distinguish the prefix type, such as tskey-api for API access tokens (sometimes called API keys) and tskey-auth for auth keys.

Key and secret types

All Tailscale-generated keys and secrets are case-sensitive.

API access tokens

API access tokens let you grant access to applications in your tailnet using the Tailscale API. You can generate and revoke your API access tokens (keys) in the Keys page of the admin console.

To create an API access token, open the Keys page of the admin console, go to the API access tokens section, then click Generate access token.

To revoke an API access token, open the Keys page of the admin console, go to the API access tokens section, then click Revoke next to the token that you want to delete.

Auth keys

Auth keys let you authenticate a tagged device in your tailnet as an alternative to an interactive single sign-on (SSO) session. You can generate and revoke auth keys in the Keys page of the admin console.

To create an auth key, see Generating a key.

To revoke an auth key, see Revoking a key.

OAuth clients

OAuth clients let you delegate and scope access for your Tailscale APIs. You can generate and revoke OAuth clients in the OAuth page of the admin console.

To create an OAuth key, see Setting up an OAuth client.

To revoke an OAuth key, see Revoking an OAuth client.

SCIM API keys

A SCIM API key lets you authenticate an identity provider, such as Microsoft Entra ID and Okta, and your tailnet for user & group provisioning. A single SCIM API key is used for an entire tailnet and is administered in the User management page of the admin console. User & group provisioning must be enabled to generate the SCIM API key. If you do not have user & group provisioning enabled in your tailnet, the User & Group Provisioning section will not display in the admin console.

To create a SCIM API key, open the User management page of the admin console and click Enable Provisioning. Copy the generated key to the clipboard, then add the key in your Microsoft Entra ID or Okta provisioning settings.

A SCIM API key should be revoked or regenerated when it is lost, the Microsoft Entra ID or Okta environment is compromised, or you've stopped using Microsoft Entra ID or Okta.

To revoke a SCIM API key, open the User management page of the admin console, and click Manage keys. In the Provisioning keys dialog, click Revoke.

To generate a new SCIM API key, open the User management page of the admin console, and click Manage keys. In the Provisioning keys dialog, click Generate new key.

Webhook secrets

Webhooks let you subscribe to tailnet events that can automatically be sent to services such as Slack, Discord, and Mattermost. A webhook secret ensures webhook requests are coming from authorized users in the tailnet. You can generate, rotate, or delete webhook secrets for your endpoints in the Webhooks page of the admin console.

To create a webhook endpoint and secret, see Setting up a webhook endpoint.

To delete a webhook endpoint, see Deleting an endpoint. When an endpoint is deleted, the secret is also deleted.

To generate a new secret for an existing webhook, see Rotating a webhook secret.

Using logs and events

You can monitor your key and secret activity in the Logs page of the admin consoles. For example, the "Create API key" event is generated when a new API access token or auth key is generated. You can also use webhooks for automatic notifications when a key status changes.

To learn more about logged events in general, see Configuration audit logging.

To learn more about the types of events related to keys that are logged, see Audit logging events.

To learn more about the types of available webhook events for key activity notifications, see Webhook events.

Key expiry

API access tokens, auth keys, and OAuth keys are generated with an expiry that you can adjust at the time they are generated. SCIM API keys and webhook endpoint secrets do not expire. As key expiry can vary across your different keys and types, make sure you are aware of the expiry day and provision accordingly for each key. For more information, see Key expiry.

Offboarding users

While key and secret management are an important aspect of security, there are other things that you should take into account when removing users and devices from your tailnet. For more information, see Offboarding users.