Linking Wallet Keys

Before you can deploy workflows to the public onchain registry (deployment-registry: "onchain:ethereum-mainnet"), 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 public CRE workflows—associating it with your organization and allowing you to deploy and manage workflows through the onchain registry.

Private registry workflows (deployment-registry: "private") do not require key linking. They are managed with your CRE login session.

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 public onchain Workflow Registry.

Key benefits:

  • Multiple team members can link their own addresses to the same organization
  • Each linked address can independently deploy and manage public onchain registry 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 constraints:

  • Permanent organization bond: Once a wallet address is linked to an organization, it is permanently bonded to that organization—even if unlinked. An unlinked address can only ever be relinked to the same organization, never to a different organization. Choose your wallet carefully before linking.
  • Per-organization key limit: The number of web3 keys your organization can link is subject to your plan quota. See Service Quotas for the current limit. To request an increase, contact us.

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 be currently linked to any CRE organization. Once linked, an address is permanently bonded to that organization.

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 with deployment-registry: "onchain:ethereum-mainnet", the CLI will detect that your address isn't linked and prompt you to link it.

Automatic linking during deployment

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

  2. Attempt to deploy a workflow:

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

  3. 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: █

  4. Enter a descriptive label for your address

  5. 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:

  1. The CLI derives your public address from the private key in .env
  2. You're prompted to provide a label
  3. The CLI checks if the address is already linked
  4. Transaction details are displayed (chain, contract address, estimated gas cost)
  5. You confirm to execute the transaction
  6. 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 public onchain registry 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 link more than one wallet address, subject to your plan's key limit. See Service Quotas for the current limit, or contact us to request an increase. Remember that each address becomes permanently bonded to your organization upon linking.

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:

  1. Update your .env file with the new private key
  2. Run cre account link-key --target <target-name> again
  3. 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:

  • Removing addresses that are no longer in use
  • Cleaning up test or development addresses

To unlink a key:

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

  2. Run the unlink command:

    cre account unlink-key --target production-settings

  3. 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.

Unlinking a key without the original private key

If you need to unlink a key but no longer have access to the original private key (for example, the key owner left your organization), you can still complete the unlinking process using a different wallet.

How it works

When you run cre account unlink-key --unsigned while logged into your CRE organization, the CLI generates:

  1. An authorization signature proving you have permission to unlink the key (through your CRE organization membership)
  2. Raw transaction data that any funded wallet can submit to the blockchain

Prerequisites

  • Logged in to CRE CLI: You must be authenticated as a member of the CRE organization that owns the key
  • workflow-owner-address configured: Set this in your project.yaml to the address you want to unlink
  • A funded wallet: Any wallet with ETH on Ethereum Mainnet to submit the transaction and pay gas fees

Steps

  1. Configure your project.yaml with the address you want to unlink:

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

  2. Generate the unsigned transaction:

    cre account unlink-key --unsigned --target production-settings

    Example output:

    Unlinking web3 key from your CRE organization
Target :                 production-settings
✔ Using Address :        0x....

Starting unlinking: owner=0x....
✔ Yes
Contract address validation passed
--unsigned flag detected: transaction not sent onchain.
Generating call data for offline signing and submission in your preferred tool:

Ownership unlinking 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:

      39d68c6a000000000000000000...

Unlinked successfully

  3. Submit the transaction using any wallet that supports sending transactions with custom data.

    Here's an example using MetaMask:

    1. In MetaMask, go to Settings → Advanced and enable "Show hex data"
    2. Click Send and enter the contract address as the recipient 0x4Ac54353FA4Fa961AfcC5ec4B118596d3305E7e5
    3. Set the amount to 0 ETH
    4. Paste the transaction data in the Hex data field (add 0x prefix)
    5. Review and confirm the transaction

    The unlink operation completes once the transaction is confirmed onchain. All workflows registered under that address will be permanently 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

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

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

  2. 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 onchain.
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

  1. Copy the transaction data provided in the CLI output
  2. Open your multi-sig interface (e.g., Safe app at https://app.safe.global)
  3. 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)
  4. Submit and collect signatures from the required number of signers
  5. 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.

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

Get the latest Chainlink content straight to your inbox.