> ## Documentation Index
> Fetch the complete documentation index at: https://siderolabs-fe86397c-1-11-reference.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Rotate SideroLink Join Token

This guide shows you how to rotate SideroLink join tokens.

Join tokens are the secret used to authenticate Talos machines' gRPC requests when they first establish a WireGuard tunnel connection to Omni.

If the token is compromised it can be revoked and replaced with the new one.

### Conditions that Make Token Rotation Possible

When a machine connects to Omni for the first time, it uses a join token specific to the Omni account that is shared by all new hosts that are registering with Omni. Omni then creates a unique, ephemeral token for each machine, and when Talos is installed to disk, that token is persisted to disk. If the shared token is revoked, machines that have persisted unique tokens (i.e. those with Talos installed to disk) will stay connected, but machines using only shared tokens will be disconnected.

<Warning>
  Talos \< 1.6 doesn't support unique tokens.
</Warning>

If Omni is started with `--join-tokens-mode=legacy`  unique node tokens are not generated for any machines. This makes rotating join tokens not possible.

### To Rotate Join Tokens

<Tabs>
  <Tab title="UI">
    #### Create New Join Token

    Click the "Join Tokens" section button under "Machine Management" in the sidebar. Next, click the "Create Join Token" button on the right.

    <img src="https://mintcdn.com/siderolabs-fe86397c-1-11-reference/YGuga1UT8xktZXw3/omni/security-and-authentication/images/rotate-siderolink-join-token-join-tokens-red-circled.png?fit=max&auto=format&n=YGuga1UT8xktZXw3&q=85&s=ef05962c41f38f37c1f8c8e7a05e0d37" alt="" width="3452" height="1870" data-path="omni/security-and-authentication/images/rotate-siderolink-join-token-join-tokens-red-circled.png" />

    <img src="https://mintcdn.com/siderolabs-fe86397c-1-11-reference/YGuga1UT8xktZXw3/omni/security-and-authentication/images/rotate-siderolink-join-token-machine-join-tokens.png?fit=max&auto=format&n=YGuga1UT8xktZXw3&q=85&s=ff1cb20e2d631cb470fa797f26feffe5" alt="" width="3454" height="1868" data-path="omni/security-and-authentication/images/rotate-siderolink-join-token-machine-join-tokens.png" />

    Give the new token a name and click the "Create Join Token" button.

    <img src="https://mintcdn.com/siderolabs-fe86397c-1-11-reference/YGuga1UT8xktZXw3/omni/security-and-authentication/images/rotate-siderolink-join-token-create-join-token.png?fit=max&auto=format&n=YGuga1UT8xktZXw3&q=85&s=152cd02aca551f8b38ccd00eaf0a2472" alt="" width="3456" height="1778" data-path="omni/security-and-authentication/images/rotate-siderolink-join-token-create-join-token.png" />

    #### Replace the default token

    If the token that you are going to revoke is the default, mark the new token as the default.

    <img src="https://mintcdn.com/siderolabs-fe86397c-1-11-reference/YGuga1UT8xktZXw3/omni/security-and-authentication/images/rotate-siderolink-join-token-machine-join-tokens-make-default.png?fit=max&auto=format&n=YGuga1UT8xktZXw3&q=85&s=64fb1528e25922453dda68902cc5c450" alt="" width="3456" height="1752" data-path="omni/security-and-authentication/images/rotate-siderolink-join-token-machine-join-tokens-make-default.png" />

    Revoke the old token. Note the warnings regarding machines that will be affected by the revocation of the old token.

    <Danger>
      If there are warnings and the token is rotated anyway, the machines in the list will get disconnected after the next restart of Omni or the machine.
    </Danger>

    <img src="https://mintcdn.com/siderolabs-fe86397c-1-11-reference/YGuga1UT8xktZXw3/omni/security-and-authentication/images/rotate-siderolink-join-token-revoke-the-token-large-token.png?fit=max&auto=format&n=YGuga1UT8xktZXw3&q=85&s=26a6991a33393bed187b7257409847f8" alt="" width="3456" height="1790" data-path="omni/security-and-authentication/images/rotate-siderolink-join-token-revoke-the-token-large-token.png" />

    If it is safe to rotate the token, Omni will show a green check mark.

    Click Revoke.

    <img src="https://mintcdn.com/siderolabs-fe86397c-1-11-reference/YGuga1UT8xktZXw3/omni/security-and-authentication/images/rotate-siderolink-join-token-revoke-the-token-small-modal.png?fit=max&auto=format&n=YGuga1UT8xktZXw3&q=85&s=2511b322c740945a50f292dd057edb0f" alt="" width="3456" height="1760" data-path="omni/security-and-authentication/images/rotate-siderolink-join-token-revoke-the-token-small-modal.png" />
  </Tab>

  <Tab title="CLI">
    Create a new jointoken

    ```
    omnictl jointoken create "next token"
    Cw4yXr6dki4ZXLaJL22xxkOkagExzTOiTSMsfaMu1UD
    ```

    If the token that you are going to revoke is the default one, mark the new token as default.

    ```
    omnictl jointoken make-default Cw4yXr6dki4ZXLaJL22xxkOkagExzTOiTSMsfaMu1UD
    ```

    Revoke the old token. Note the warnings regarding machines that will be affected by the revocation of the old token.

    <Danger>
      If there are warnings and the token is rotated anyway, the machines in the list will get disconnected after the next restart of Omni or the machine.
    </Danger>

    ```
    omnictl jointoken revoke w7uVuW3zbVKIYQuzEcyetAHeYMeo5q2L9RvkAVfCfSCD
    WARNING: 11 of 12 machines won't be able to connect if the token is revoked/deleted
    MACHINE                                DETAILS
    0852139d-7725-4fa0-8d4d-98a7b3d280d4   Talos version installed does not support unique node tokens
    30ae176b-4f72-4a31-b2c0-19878a8daf4f   Talos version installed does not support unique node tokens
    43c505f2-b7f8-4aed-abd9-7697a206da1a   Talos version installed does not support unique node tokens
    6a1eefff-5c3f-4842-8547-b6d69bbea133   Talos version installed does not support unique node tokens
    77b829e6-2020-4414-ba63-2c3778d9d225   Talos is not installed so the generated node unique token is ephemeral
    96faf29f-5d2f-491c-a9b3-70f554e29092   Talos is not installed so the generated node unique token is ephemeral
    af1fd286-0c99-4e0a-9f9a-13827c98510e   Talos is not installed so the generated node unique token is ephemeral
    bebad6c2-190f-4af0-91ce-954e838f0e5c   Talos is not installed so the generated node unique token is ephemeral
    c9105e60-865c-491b-af8e-fe7e16b3f1e0   Talos is not installed so the generated node unique token is ephemeral
    dc42bc15-afc4-40fe-b309-1b84e9f439e1   Talos version installed does not support unique node tokens
    fff36bbc-0ba3-4775-9859-394ffbd9c0ed   Talos version installed does not support unique node tokens
    Do you still want to revoke the token? [y/N]:
    ```

    If the token can be safely revoked, the operation will continue without asking.
  </Tab>
</Tabs>

You can copy now the new token and start using it.