# Linking Wallet Keys
Source: https://docs.chain.link/cre/organization/linking-keys
Last Updated: 2025-11-04


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 constraints:**

- **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](#unlinking-a-key) from the current organization.
- **Maximum 2 keys per organization**: Each organization can link a maximum of 2 web3 keys. If you need to link a third key, you must first [unlink](#unlinking-a-key) one of the existing keys.

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.

<Aside type="note" title="Already linked to another organization?">
  If you try to link an address that's already registered with another organization, the CLI will display an error. To use this address with your current organization, you must first unlink it from the other organization using <CopyText text="cre account unlink-key" code /> (note: this will delete all workflows registered under that address in the other organization).
</Aside>

## Prerequisites

Before linking a key, ensure you have:

- **CRE CLI installed and authenticated**: See [CLI Installation](/cre/getting-started/cli-installation) and [Logging in with the CLI](/cre/account/cli-login)
- **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.

> **CAUTION: Never commit your .env file**
>
> Your `.env` file contains sensitive private keys. Ensure it's listed in `.gitignore` and never committed to version control.

## 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](/cre/guides/operations/deploying-workflows), 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:

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

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

   ```bash
   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:

```bash
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:**

```bash
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:

```bash
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:

```bash
cre account list-key
```

**Example output:**

```bash
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

> **NOTE: Organization-wide visibility**
>
> All members of your organization can see all linked addresses using `cre account list-key`. This helps teams coordinate workflow ownership and deployment.

## Linking multiple addresses

Your organization can link **up to 2 wallet addresses**. 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:

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:

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

> **CAUTION: Destructive operation**
>
> **Unlinking a key will permanently delete all workflows registered under that address.** This action cannot be undone. Make sure you want to permanently remove all associated workflows before proceeding.

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:

   ```bash
   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.

> **CAUTION: Destructive operation**
>
> **Unlinking a key will permanently delete all workflows registered under that address.** This action cannot be undone. Make sure you want to permanently remove all associated workflows before proceeding.

### 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

> **NOTE: Security**
>
> The authorization is tied to the **organization**, not to the individual who originally linked the key. Any authenticated member of the CRE organization can generate valid unlink authorization for keys linked to that organization.

### 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:

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

2. **Generate the unsigned transaction**:

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

   **Example output:**

   ```bash
   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 on-chain.
   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.

> **CAUTION: Destructive operation**
>
> **Unlinking a key will permanently delete all workflows registered under that address.** This action cannot be undone. Make sure you want to permanently remove all associated workflows before proceeding.

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:

```bash
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:

   ```yaml
   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:

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

**Example output:**

```bash
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

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](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 <a href="https://etherscan.io/address/0x4Ac54353FA4Fa961AfcC5ec4B118596d3305E7e5#code" target="_blank" rel="noopener noreferrer">Etherscan</a>.

### Verifying the multi-sig link

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

```bash
cre account list-key
```

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

```bash
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.

> **NOTE: Multi-sig for workflow operations**
>
> Once your multi-sig address is linked, you'll also need to use the `--unsigned` flag for workflow deployment and management commands (`deploy`, `activate`, `pause`, `delete`). See the [Deploying Workflows guide](/cre/guides/operations/deploying-workflows) for more details on using multi-sig wallets with workflow operations.

## Learn more

- **[Understanding Organizations](/cre/organization/understanding-organizations)** - Learn about organization structure and shared resources
- **[Using Multi-sig Wallets](/cre/guides/operations/using-multisig-wallets)** - Advanced guide for multi-sig wallet workflows
- **[Account Management CLI Reference](/cre/reference/cli/account)** - Complete reference for `cre account` commands
- **[Deploying Workflows](/cre/guides/operations/deploying-workflows)** - Deploy your first workflow after linking a key