Configure JWT authentication
This guidance is relevant only if your beacon node is connecting to your execution node over HTTP. If you're using IPC, you can ignore this. If you want to learn how to use IPC, see our Quickstart.
First, select a configuration:
- Operating system:
- Linux, MacOS, Arm64
- Windows
- Network:
- Mainnet
- Goerli-Prater
- Sepolia
- Holesky
- Execution client:
- Geth
- Nethermind
- Besu
- EN-BN connection:
- HTTP-JWT
- IPC
The HTTP connection between your beacon node and execution node needs to be authenticated using a JWT token. There are several ways to generate this JWT token:
- Use a utility like OpenSSL to create the token via command:
openssl rand -hex 32 | tr -d "\n" > "jwt.hex"
. - Use an execution client to generate the
jwt.hex
file. - Use Prysm to generate the
jwt.hex
file:
- Operating system:
- Linux, MacOS, Arm64
- Windows
## Optional. This command is necessary only if you've previously configured USE_PRYSM_VERSION
SET USE_PRYSM_VERSION=v4.0.0
## Required.
prysm.bat beacon-chain generate-auth-secret
## Optional. This command is necessary only if you've previously configured USE_PRYSM_VERSION
USE_PRYSM_VERSION=v4.0.0
## Required.
./prysm.sh beacon-chain generate-auth-secret
Prysm will output a jwt.hex
file path.
Ensure that the script, user, or terminal window used to create and access your JWT token has the permissions it needs. Windows users may need to run command windows as Administrator.
Configure execution node
Your execution node needs to expose a new port and then use the JWT token to authenticate your beacon node's connection to that port.
Using the latest version of your execution client software, issue the following command to configure your execution node's JWT token and Engine API endpoint:
- Execution client:
- Nethermind
- Besu
- Geth
Download the latest stable release of Nethermind for your operating system from the Nethermind downloads page. Extract the contents into your execution
folder. Run the following command to start your execution node:
- Mainnet
- Goerli-Prater
- Sepolia
- Holesky
- JWT
- IPC
Nethermind.Runner --JsonRpc.Enabled true --HealthChecks.Enabled true --HealthChecks.UIEnabled true --JsonRpc.JwtSecretFile=/path/to/jwt.hex
Nethermind.Runner --JsonRpc.Enabled true --HealthChecks.Enabled true --HealthChecks.UIEnabled true --JsonRpc.IpcUnixDomainSocketPath=/path/to/<your.ipc>
- JWT
- IPC
Nethermind.Runner --config goerli --JsonRpc.Enabled true --HealthChecks.Enabled true --HealthChecks.UIEnabled true --JsonRpc.JwtSecretFile=/path/to/jwt.hex
Nethermind.Runner --config goerli --JsonRpc.Enabled true --HealthChecks.Enabled true --HealthChecks.UIEnabled true --JsonRpc.IpcUnixDomainSocketPath=/path/to/<your.ipc>
- JWT
- IPC
Nethermind.Runner --config sepolia --JsonRpc.Enabled true --HealthChecks.Enabled true --HealthChecks.UIEnabled true --JsonRpc.JwtSecretFile=/path/to/jwt.hex --Merge.TerminalTotalDifficulty 17000000000000000
Nethermind.Runner --config sepolia --JsonRpc.Enabled true --HealthChecks.Enabled true --HealthChecks.UIEnabled true --JsonRpc.IpcUnixDomainSocketPath=/path/to/<your.ipc> --Merge.TerminalTotalDifficulty 17000000000000000
- JWT
- IPC
Nethermind.Runner --config holesky --JsonRpc.Enabled true --HealthChecks.Enabled true --HealthChecks.UIEnabled true --JsonRpc.JwtSecretFile=/path/to/jwt.hex
Nethermind.Runner --config holesky --JsonRpc.Enabled true --HealthChecks.Enabled true --HealthChecks.UIEnabled true --JsonRpc.IpcUnixDomainSocketPath=/path/to/<your.ipc>
See Nethermind's command-line options for parameter definitions.
Ensure that the latest 64-bit version of the Java JDK is installed. Download the latest stable release of Besu from the Besu releases page. OS-specific instructions are available on Besu's binary installation page. Run the following command to start your execution node:
- Mainnet
- Goerli-Prater
- Sepolia
- Holesky
- JWT
- IPC
besu --rpc-http-enabled --engine-jwt-enabled=true --engine-jwt-secret=path/to/jwt.hex --engine-host-allowlist="*"
Content under construction.
- JWT
- IPC
besu --network=goerli --rpc-http-enabled --engine-jwt-enabled=true --engine-jwt-secret=path/to/jwt.hex --engine-host-allowlist="*"
Content under construction.
- JWT
- IPC
besu --network=sepolia --rpc-http-enabled --engine-jwt-enabled=true --engine-jwt-secret=/path/to/jwt.hex --engine-host-allowlist="*" --override-genesis-config="terminalTotalDifficulty=17000000000000000"
Content under construction.
- JWT
- IPC
besu --network=holesky --rpc-http-enabled --engine-jwt-enabled=true --engine-jwt-secret=/path/to/jwt.hex --engine-host-allowlist="*"
Content under construction.
See Besu's command-line options for parameter definitions.
Download and run the latest 64-bit stable release of the Geth installer for your operating system from the Geth downloads page.
Navigate to your execution
directory and run the following command to start your execution node:
- Mainnet
- Goerli-Prater
- Sepolia
- Holesky
- JWT
- IPC
geth --http --http.api eth,net,engine,admin --authrpc.jwtsecret /path/to/jwt.hex
geth --http --http.api eth,net,engine,admin
- JWT
- IPC
geth --goerli --http --http.api eth,net,engine,admin --authrpc.jwtsecret /path/to/jwt.hex
geth --goerli --http --http.api eth,net,engine,admin
- JWT
- IPC
geth --sepolia --http --http.api eth,net,engine,admin --authrpc.jwtsecret /path/to/jwt.hex
geth --sepolia --http --http.api eth,net,engine,admin
- JWT
- IPC
geth --holesky --http --http.api eth,net,engine,admin --authrpc.jwtsecret /path/to/jwt.hex
geth --holesky --http --http.api eth,net,engine,admin
See Geth's command-line options for parameter definitions.
Syncing can take a long time - from hours to days. You can proceed to the next step while your execution node syncs.
Configure beacon node
Next, we'll configure your beacon node to consume your JWT token so it can form an authenticated HTTP connection with your execution node.
In this step, you'll run a beacon node using Prysm.
- Windows
- Linux, MacOS, Arm64
- Mainnet
- Goerli-Prater
- Sepolia
- Holesky
Use the following command to start a beacon node that connects to your local execution node:
- JWT
- IPC
prysm.bat beacon-chain --execution-endpoint=http://localhost:8551 --jwt-secret=path/to/jwt.hex --suggested-fee-recipient=0x01234567722E6b0000012BFEBf6177F1D2e9758D9
--http-web3provider
is deprecated and has been replaced with --execution-endpoint
, but IPC currently only works through --http-web3provider
on Windows. This will be fixed in our next release. You can safely ignore any related "deprecated flag" warnings you see in the meantime.
prysm.bat beacon-chain --http-web3provider=//./pipe/<your.ipc> --suggested-fee-recipient=0x01234567722E6b0000012BFEBf6177F1D2e9758D9
Download the Prater genesis state from Github into your consensus/prysm
directory. Then use the following command to start a beacon node that connects to your local execution node:
- JWT
- IPC
prysm.bat beacon-chain --execution-endpoint=http://localhost:8551 --prater --jwt-secret=path/to/jwt.hex --genesis-state=genesis.ssz --suggested-fee-recipient=0x01234567722E6b0000012BFEBf6177F1D2e9758D9
--http-web3provider
is deprecated and has been replaced with --execution-endpoint
, but IPC currently only works through --http-web3provider
on Windows. This will be fixed in our next release. You can safely ignore any related "deprecated flag" warnings you see in the meantime.
prysm.bat beacon-chain --http-web3provider=//./pipe/<your.ipc> --prater --genesis-state=genesis.ssz --suggested-fee-recipient=0x01234567722E6b0000012BFEBf6177F1D2e9758D9
Download the Sepolia genesis state from Github into your consensus/prysm
directory. Then use the following command to start a beacon node that connects to your local execution node:
- JWT
- IPC
prysm.bat beacon-chain --execution-endpoint=http://localhost:8551 --sepolia --suggested-fee-recipient=0x01234567722E6b0000012BFEBf6177F1D2e9758D9 --jwt-secret=jwt.hex --genesis-state=genesis.ssz
--http-web3provider
is deprecated and has been replaced with --execution-endpoint
, but IPC currently only works through --http-web3provider
on Windows. This will be fixed in our next release. You can safely ignore any related "deprecated flag" warnings you see in the meantime.
prysm.bat beacon-chain --http-web3provider=//./pipe/<your.ipc> --sepolia --suggested-fee-recipient=0x01234567722E6b0000012BFEBf6177F1D2e9758D9 --genesis-state=genesis.ssz
Download the Holesky genesis state from Github into your consensus/prysm
directory. Then use the following command to start a beacon node that connects to your local execution node:
- JWT
- IPC
prysm.bat beacon-chain --execution-endpoint=http://localhost:8551 --holesky --suggested-fee-recipient=0x01234567722E6b0000012BFEBf6177F1D2e9758D9 --jwt-secret=jwt.hex --genesis-state=genesis.ssz
prysm.bat beacon-chain --execution-endpoint=//./pipe/<your.ipc> --holesky --suggested-fee-recipient=0x01234567722E6b0000012BFEBf6177F1D2e9758D9 --genesis-state=genesis.ssz
- Mainnet
- Goerli-Prater
- Sepolia
- Holesky
Use the following command to start a beacon node that connects to your local execution node:
- JWT
- IPC
./prysm.sh beacon-chain --execution-endpoint=http://localhost:8551 --jwt-secret=path/to/jwt.hex --suggested-fee-recipient=0x01234567722E6b0000012BFEBf6177F1D2e9758D9
./prysm.sh beacon-chain --execution-endpoint=$HOME/.ethereum/<your.ipc> --suggested-fee-recipient=0x01234567722E6b0000012BFEBf6177F1D2e9758D9
Download the Prater genesis state from Github into your consensus/prysm
directory. Then use the following command to start a beacon node that connects to your local execution node:
- JWT
- IPC
./prysm.sh beacon-chain --execution-endpoint=http://localhost:8551 --prater --jwt-secret=path/to/jwt.hex --genesis-state=genesis.ssz --suggested-fee-recipient=0x01234567722E6b0000012BFEBf6177F1D2e9758D9
./prysm.sh beacon-chain --execution-endpoint=$HOME/.ethereum/<your.ipc> --prater --genesis-state=genesis.ssz --suggested-fee-recipient=0x01234567722E6b0000012BFEBf6177F1D2e9758D9
Download the Sepolia genesis state from Github into your consensus/prysm
directory. Then use the following command to start a beacon node that connects to your local execution node:
- JWT
- IPC
./prysm.sh beacon-chain --execution-endpoint=http://localhost:8551 --sepolia --suggested-fee-recipient=0x01234567722E6b0000012BFEBf6177F1D2e9758D9 --jwt-secret=jwt.hex --genesis-state=genesis.ssz
./prysm.sh beacon-chain --execution-endpoint=$HOME/.ethereum/<your.ipc> --sepolia --suggested-fee-recipient=0x01234567722E6b0000012BFEBf6177F1D2e9758D9 --genesis-state=genesis.ssz
Download the Holesky genesis state from Github into your consensus/prysm
directory. Then use the following command to start a beacon node that connects to your local execution node:
- JWT
- IPC
./prysm.sh beacon-chain --execution-endpoint=http://localhost:8551 --holesky --suggested-fee-recipient=0x01234567722E6b0000012BFEBf6177F1D2e9758D9 --jwt-secret=jwt.hex --genesis-state=genesis.ssz
./prysm.sh beacon-chain --execution-endpoint=$HOME/.ethereum/<your.ipc> --holesky --suggested-fee-recipient=0x01234567722E6b0000012BFEBf6177F1D2e9758D9 --genesis-state=genesis.ssz
If you're running a validator, specifying a suggested-fee-recipient
wallet address will allow you to earn what were previously miner transaction fee tips. See How to configure Fee Recipient for more information about this feature.
Your beacon node will now begin syncing. This usually takes a couple days, but it can take longer depending on your network and hardware specs.
Congratulations - you’re now running a full, Merge-ready Ethereum node. To check the status of your node, visit Check node and validator status.
Congrats! You're now using JWT authentication.