Linking Wallet Keys

Before you can deploy workflows, you must link a public key address to your CRE organization. This process registers your wallet address onchain in the Workflow Registry contract—the smart contract on Ethereum Mainnet that stores and manages all CRE workflows—associating it with your organization and allowing you to deploy and manage workflows.

What is key linking?

Key linking is the process of connecting a blockchain wallet address to your CRE organization. Once linked, this address becomes a workflow owner address that can deploy, update, and delete workflows in the Workflow Registry.

Key benefits:

Multiple team members can link their own addresses to the same organization
Each linked address can independently deploy and manage workflows
Addresses are labeled for easy identification (e.g., "Production Wallet", "Dev Wallet")
All linked addresses are visible to organization members via cre account list-key

Important constraint:

One organization per address: Each wallet address can only be linked to one CRE organization at a time. If you need to use the same address with a different organization, you must first unlink it from the current organization.

However, an organization can have multiple wallet addresses linked to it, allowing team members to use their own addresses or enabling separation between development, staging, and production environments.

Prerequisites

Before linking a key, ensure you have:

CRE CLI installed and authenticated: See CLI Installation and Logging in with the CLI
A CRE project directory: You must run the command from a project directory that contains a project.yaml file
Private key in .env: Set CRE_ETH_PRIVATE_KEY=<your_64_character_hex_key> (without 0x prefix) in your .env file
Funded wallet: Your wallet must have ETH on Ethereum Mainnet to pay for gas fees (the Workflow Registry contract is deployed on Ethereum Mainnet)
Unlinked address: The wallet address must not already be linked to another CRE organization. Each address can only be associated with one organization at a time.

Linking your first key

The easiest way to link a key is to let the deployment process handle it automatically. When you first try to deploy a workflow, the CLI will detect that your address isn't linked and prompt you to link it.

Automatic linking during deployment

Navigate to your project directory (where your .env file is located)

Attempt to deploy a workflow:

cre workflow deploy my-workflow --target production-settings

The CLI will detect that your address isn't linked and prompt you:

Verifying ownership...
Workflow owner link status: owner=<your_owner_address>, linked=false
Owner not linked. Attempting auto-link: owner=<your_owner_address>
Linking web3 key to your CRE organization
Target :                 production-settings
✔ Using Address :        <your_owner_address>

✔ Provide a label for your owner address: █

Enter a descriptive label for your address
Review the transaction details and confirm

The CLI will submit the transaction and continue with the deployment once the key is linked.

Manual linking

You can also link a key manually before attempting to deploy:

cre account link-key --target production-settings

Interactive flow:

The CLI derives your public address from the private key in .env
You're prompted to provide a label
The CLI checks if the address is already linked
Transaction details are displayed (chain, contract address, estimated gas cost)
You confirm to execute the transaction
The transaction is submitted and you receive a block explorer link

Example output:

Linking web3 key to your CRE organization
Target :                 production-settings
✔ Using Address :        <your_owner_address>

Provide a label for your owner address: <your_owner_label>

Checking existing registrations...
✓ No existing link found for this address
Starting linking: owner=<your_owner_address>, label=<your_owner_label>
Contract address validation passed
Transaction details:
  Chain Name:   ethereum-mainnet
  To:           0x4Ac54353FA4Fa961AfcC5ec4B118596d3305E7e5 # Workflow Registry contract address
  Function:     LinkOwner
  ...
Estimated Cost:
  Gas Price:      0.12450327 gwei
  Total Cost:     0.00001606 ETH
? Do you want to execute this transaction?:
  ▸ Yes
    No

After confirming, you'll see:

Transaction confirmed
View on explorer: https://etherscan.io/tx/<your_transaction_hash>

[OK] web3 address linked to your CRE organization successfully

→ You can now deploy workflows using this address

Viewing linked keys

To see all addresses linked to your organization:

cre account list-key

Example output:

Workflow owners retrieved successfully:

Linked Owners:

  1. JohnProd
     Owner Address:     <public_owner_address>
     Status:            VERIFICATION_STATUS_SUCCESSFULL
     Verified At:       2025-10-21T17:22:24.394249Z
     Chain Selector:    5009297550715157269 # Chain selector for Ethereum Mainnet
     Contract Address:  0x4Ac54353FA4Fa961AfcC5ec4B118596d3305E7e5 # Workflow Registry contract address

  2. JaneProd
     Owner Address:     <public_owner_address>
     Status:            VERIFICATION_STATUS_SUCCESSFULL
     Verified At:       2025-10-21T17:22:24.394249Z
     Chain Selector:    5009297550715157269 # Chain selector for Ethereum Mainnet
     Contract Address:  0x4Ac54353FA4Fa961AfcC5ec4B118596d3305E7e5 # Workflow Registry contract address

Understanding the output:

Label: The friendly name you provided (e.g., "JohnProd", "JaneProd")
Owner Address: The public address linked to your organization
Status: VERIFICATION_STATUS_SUCCESSFULL (linked and verified)
Verified At: Timestamp when the link was confirmed onchain
Chain Selector: The chain identifier where the Workflow Registry contract is deployed
Contract Address: The Workflow Registry contract address

Linking multiple addresses

Your organization can have multiple wallet addresses linked to it simultaneously, but remember that each individual address can only be linked to one organization at a time.

This is useful for:

Separation of concerns: Different addresses for development, staging, and production
Team collaboration: Each team member uses their own address
Multi-sig wallets: Link a multi-sig address alongside individual addresses

To link another address:

Update your .env file with the new private key
Run cre account link-key --target <target-name> again
Provide a unique label to distinguish this address

Unlinking a key

If you need to remove a linked address from your organization, you can use the cre account unlink-key command. This is useful when:

Rotating addresses for security reasons
Removing addresses that are no longer in use
Cleaning up test or development addresses

To unlink a key:

Ensure your .env file contains the private key of the address you want to unlink

Run the unlink command:

cre account unlink-key --target production-settings

Confirm the operation when prompted

The CLI will submit an onchain transaction to remove the address from the Workflow Registry. After the transaction is confirmed, the address and all its associated workflows will be deleted.

Non-interactive mode

For automation or CI/CD pipelines, use the --yes flag to skip confirmation prompts:

cre account link-key --owner-label "CI Pipeline Wallet" --yes --target production-settings

Using multi-sig wallets

If you're using a multi-sig wallet, you'll need to use the --unsigned flag to generate raw transaction data that you can then submit through your multi-sig interface (such as Safe).

Prerequisites for multi-sig

Configure your multi-sig address in project.yaml under the account section:

production-settings:
  account:
    workflow-owner-address: "<your_multisig_address>"
  # ... other settings

Ensure your .env file contains the private key of any signer from the multi-sig wallet (used only for signature generation, not for sending transactions)

Linking a multi-sig address

Run the link-key command with the --unsigned flag:

cre account link-key --owner-label "SafeWallet" --target production-settings --unsigned

Example output:

Linking web3 key to your CRE organization
Target :                 production-settings
✔ Using Address :        <your_multisig_address>

Checking existing registrations...
✓ No existing link found for this address
Starting linking: owner=<your_multisig_address>, label=SafeWallet
Contract address validation passed
--unsigned flag detected: transaction not sent on-chain.
Generating call data for offline signing and submission in your preferred tool:

Ownership linking initialized successfully!

Next steps:

   1. Submit the following transaction on the target chain:
      Chain:            ethereum-mainnet
      Contract Address: 0x4Ac54353FA4Fa961AfcC5ec4B118596d3305E7e5

   2. Use the following transaction data:

      dc1019690000000000000000000000000000000000000000000000000000000068fd2f9465259a804e880ee30de0fcc2b81ee25d598ee1601e13ace2c2ec10202869706800000000000000000000000000000000000000000000000000000000000000600000000000000000000000000000000000000000000000000000000000000041bd0f40824a1fdce10ee1091703833fb3d4497b3f681f6edee6b159d217326185407ce16eb1c668c90786421b053d4d25401f422aa90d156c35659d7c3e2e13221b00000000000000000000000000000000000000000000000000000000000000

Linked successfully

Submitting through your multi-sig interface

Copy the transaction data provided in the CLI output
Open your multi-sig interface (e.g., Safe app at https://app.safe.global)
Create a new transaction with:
- To address: 0x4Ac54353FA4Fa961AfcC5ec4B118596d3305E7e5 (Workflow Registry contract)
- Value: 0 (no ETH transfer)
- Data: Paste the transaction data from the CLI output (add 0x prefix if required by your multi-sig interface)
Submit and collect signatures from the required number of signers
Execute the transaction once you have enough signatures

Note: If your multi-sig interface requires the RegistryWorkflow contract ABI, you can copy it from Etherscan.

Verifying the multi-sig link

After the multi-sig transaction is executed onchain, you can verify the link status:

cre account list-key

Initially, you'll see the address with a VERIFICATION_STATUS_PENDING status:

Workflow owners retrieved successfully:

Linked Owners:

  1. SafeWallet
     Owner Address:     <your_multisig_address>
     Status:            VERIFICATION_STATUS_PENDING
     Verified At:
     Chain Selector:    5009297550715157269 # Chain selector for Ethereum Mainnet
     Contract Address:  0x4Ac54353FA4Fa961AfcC5ec4B118596d3305E7e5 # Workflow Registry contract address

Once the transaction is confirmed onchain, the status will change to VERIFICATION_STATUS_SUCCESSFULL and the Verified At timestamp will be populated.

Learn more

Understanding Organizations - Learn about organization structure and shared resources
Using Multi-sig Wallets - Advanced guide for multi-sig wallet workflows
Account Management CLI Reference - Complete reference for cre account commands
Deploying Workflows - Deploy your first workflow after linking a key

Linking Wallet Keys

Get the latest Chainlink content straight to your inbox.