Safely Retrieve and Rotate Docker Swarm Join Tokens

A join token behaves like a password for your cluster, so docker swarm join-token deserves more care than most read commands get. You will retrieve the command for adding a worker or manager, extract only the token when automation needs it, and rotate a token after a suspected leak. Allow about ten minutes.

You need Docker Engine running on a swarm manager, and permission to access its Docker daemon. These commands inspect or change swarm credentials; they are not ordinary commands to run on an untrusted worker.

1. Confirm that you are on a manager

docker swarm join-token is a cluster-management command. Run it on a node that is already a swarm manager; it does not create a swarm and cannot be used from a worker node.

$ docker info --format '{{.Swarm.LocalNodeState}} {{.Swarm.ControlAvailable}}'
active true

The exact output depends on the Docker daemon, but you need an active swarm and control-plane access. This guide was checked with Docker Community CLI 29.8.1 from package docker-ce-cli 5:29.8.1-1~ubuntu.24.04~noble. The local manual documents the same two options used below: --quiet and --rotate.

If Docker reports that this node is not a swarm manager, stop here. Do not run docker swarm init just to make this check pass: initialising a node creates a new swarm, a separate administrative decision.

2. Print a worker join command

Use the role as the final argument. The normal form prints a complete docker swarm join command containing the token and the manager's advertised address:

$ docker swarm join-token worker
To add a worker to this swarm, run the following command:

    docker swarm join \
    --token SWMTKN-1-<worker-token> \
    <manager-address>:2377

Copy the generated join command only to the machine about to become a worker. The token is a credential, not a label. Avoid putting this output in shell history, tickets, chat or build logs. Port 2377 is shown by Docker's generated command in the usual configuration, but use the address and port Docker actually prints for your swarm.

On the new node, run the generated command as the account that can access that node's Docker daemon. A successful join changes that node's Docker state and switches it into swarm mode; this guide does not run the join command for you.

Checkpoint: After a join, return to a manager and verify membership.

$ docker node ls

Look for the expected hostname and role. The command must be run on a manager.

3. Print a manager join command only when needed

Manager tokens are more sensitive than worker tokens. A node joining with the manager token can participate in swarm management, so use this role only when you have a specific reason to add a manager:

$ docker swarm join-token manager
To add a manager to this swarm, run the following command:

    docker swarm join \
    --token SWMTKN-1-<manager-token> \
    <manager-address>:2377

Keep manager and worker tokens separate in your notes and automation. Both are accepted only for their corresponding role, and a manager token does not turn an existing worker into a manager; it is used when a new node joins.

4. Extract only a token for automation

Pass --quiet when another command needs the credential and not Docker's explanatory join command. It prints only the token for the selected role:

$ docker swarm join-token --quiet worker
SWMTKN-1-<worker-token>

For a script, capture it in a variable without echoing it:

token=$(docker swarm join-token --quiet worker) || exit $?
printf '%s' 'Worker token retrieved without printing its value'

5. Rotate a leaked or obsolete token

Rotation changes the token for one role. It invalidates the previous token for future joins, but does not remove nodes that have already joined, since tokens are used only at join time.

Warning: Rotation can break a pending provisioning job that still holds the old token. Coordinate first if another machine is currently joining, then rotate the affected role:

$ docker swarm join-token --rotate worker
Successfully rotated worker join token.

To add a worker to this swarm, run the following command:

    docker swarm join \
    --token SWMTKN-1-<new-worker-token> \
    <manager-address>:2377

Use manager instead of worker when the manager credential was exposed. Do not rotate both automatically unless you have checked which onboarding flows depend on each token.

After rotation, fetch the current value with:

$ docker swarm join-token --quiet worker

Recovery: there is no undo command that restores the old token. Distribute the newly printed token to authorised provisioning systems and retry any join that was using the old one; existing swarm members need no rejoin because of token rotation.

6. Diagnose the common failures

docker swarm join-token fails when the daemon is not running, when the node is not a manager, or when the Docker client cannot access the daemon. Check the context and daemon without changing swarm state:

$ docker context show
$ docker info --format '{{.Swarm.LocalNodeState}} {{.Swarm.ControlAvailable}}'

Make sure the context points to the intended manager. If the output says inactive false, you are not holding the control-plane role this command needs. If access is denied, fix the Docker daemon access for the account you intend to use rather than copying a token to a different machine.

If a generated join command fails on the new node, preserve the error text and check network reachability to the manager address and the swarm control port Docker shows. Do not regenerate or rotate a token repeatedly as a substitute for diagnosing connectivity; a token can be valid while the node cannot reach the manager.

Done means