> For the complete documentation index, see [llms.txt](https://help.enterprise.ledger.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.enterprise.ledger.com/help-center-v2/administration/onboarding.md). # Workspace onboarding The key ceremony that creates a Ledger Enterprise Workspace: who attends, the hosted and on-premises variants, each step, and what the ceremony produces. Workspace onboarding is the key ceremony that creates your Workspace. It runs one time, before anyone can sign in to the Ledger Enterprise interface. **Role: the first three Administrators of a new Workspace, and its three Shared Owners.** ## What the ceremony is Ledger creates the onboarding for your organization and gives you an **onboarding ID**. The ceremony then runs in the **Onboarding app**, a separate application from the Ledger Enterprise interface. The participants connect their Ledger devices to the Onboarding app, one device at a time. The ceremony has two variants. Ledger sets the variant when it creates the onboarding. | | Hosted Workspace | On-premises Workspace | | --------------------------------------------- | ------------------------------------------------------------------------- | ---------------------------------------- | | Where the Hardware Security Module (HSM) runs | Ledger hosts it | On your organization's premises | | Ledger devices | 6: 3 Administrator devices and 3 Shared Owner devices | 3 Administrator devices | | Master seed | Generated in the HSM from three shards, one from each Shared Owner device | No Shared Owners and no master seed step | | Specific step | **Register shared owners** and **Collect shards** | **Register external signer** | Each device holds one role for the whole ceremony. The Onboarding app shows the roles as **Administrator** and **Shared Owner**. An Administrator of the ceremony becomes a Master Administrator of the Workspace. ## Before the ceremony * Each participant has a Ledger Stax that is set up with a PIN. See [**Your security device**](/help-center-v2/start-here/get-started/your-device.md). * Each device runs the firmware and the Ledger Vault app version that Ledger Enterprise requires. On the Onboarding app home page, select **Update my device** to check a device and install the updates. * The Administrators agree on their three Administrator names. See [Administrator names](#administrator-names). ## Join the ceremony 1. Open the Onboarding app. 2. In **Your Onboarding ID**, enter the onboarding ID that Ledger gave you. 3. Select **Join my organization**. 4. Select **Start**. If the ceremony has already started, the page shows the current step, and the button reads **Join session**. The side panel of the Onboarding app shows the ceremony as **Key ceremony**, with the steps that your team completed. ## The steps of a hosted Workspace The Onboarding app names each step in its side panel. The steps run in this order. ### 1. Declare required devices Each device is assigned to a role, and checked before it joins the ceremony. 1. Select **Claim**. 2. Select **Administrator device** or **Shared Owner device**. 3. Select **Claim an Administrator device** or **Claim a Shared Owner device**. 4. Connect the device. 5. Unlock the device. 6. Follow the checks on the screen. The Onboarding app checks the firmware and the Ledger Vault app, and offers to install updates. 7. Select **Claim**. 8. Do these steps again for each device: 3 Administrator devices and 3 Shared Owner devices. 9. Select **Continue**. A device can be claimed one time only. To correct a claim, open the menu on the device card. Then select **Un-claim**. Each role takes exactly 3 devices. ### 2. Register administrators Each Administrator device registers a user in the HSM. 1. Select **Start**. 2. Connect an Administrator device. 3. In **Administrator name**, enter the name of this Administrator. 4. Select **Onboard my device**. 5. Follow the instructions on the Ledger device. 6. Do these steps again for the two other Administrator devices. 7. Select **Continue**. When you select **Continue**, the HSM creates the Master Administrator group of the three Administrators, with a quorum of 2. ### 3. Register shared owners Each Shared Owner device registers in the HSM, so that it can contribute to the master seed later. A Shared Owner does not enter a name: the Onboarding app names each Shared Owner from its device ID. 1. Select **Start**. 2. Connect a Shared Owner device. 3. Select **Onboard my device**. 4. Follow the instructions on the Ledger device. 5. Do these steps again for the two other Shared Owner devices. 6. Select **Continue**. ### 4. Workspace settings The three Administrators review the default settings of the Workspace and the registered users. Each approval is a signature from an Administrator device. 1. Select **Start**. 2. Connect an Administrator device. 3. Select **Review settings**. 4. Review the details on the Ledger device. 5. Approve on the Ledger device. 6. Do these steps again for the two other Administrator devices. 7. Select **Continue**. All three Administrators must approve. A quorum of 2 is not enough at this step. ### 5. Collect shards Each Shared Owner device approves the onboarding details and sends its shard of the master seed to the HSM. The shard travels encrypted. 1. Select **Start**. 2. Connect a Shared Owner device. 3. Select **Collect my shard**. 4. Follow the instructions on the Ledger device. 5. Do these steps again for the two other Shared Owner devices. 6. Select **Continue**. The HSM generates the master seed from the three shards. See [The master seed](#the-master-seed). ### 6. Launch workspace 1. Select **Launch** followed by your Workspace name. 2. When the page shows that your Workspace is ready, select **Download summary**. 3. Select **Go to** followed by your Workspace name to open the Ledger Enterprise interface. ## The steps of an on-premises Workspace An on-premises Workspace has no Shared Owners. Its steps are: 1. **Declare required devices**, with 3 Administrator devices only. 2. **Register administrators**, as for a hosted Workspace. 3. **Workspace settings**. The three Administrators approve the Master Administrator group. 4. **Register external signer**. The three Administrators approve the external signer that the HSM uses to create the Workspace partition. Each Administrator selects **Review external signer**, then approves on the Ledger device. 5. **Launch workspace**, as for a hosted Workspace. After the launch, Master Administrators manage the external signer keys in [**Workspace settings**](/help-center-v2/administration/governance/workspace-settings.md#external-signers). ## What the ceremony produces * **The Workspace**, with the name that Ledger set when it created the onboarding. * **Three Master Administrators.** Each one is a Personal Security Device (PSD) user with the Administrator role, and signs in with their Ledger device. * **The Master Administrator quorum of 2.** Each Workspace governance Request needs the approval of 2 Master Administrators. See [**Workspace settings**](/help-center-v2/administration/governance/workspace-settings.md). * **The master seed**, in the HSM of a hosted Workspace. * **The onboarding summary**, a PDF file titled "Ledger Enterprise Onboarding Summary". The summary holds the Workspace name, the onboarding ID and the completion date. For each Shared Owner device, it gives the public key and the device ID. For each Administrator device, it also gives the user name. The ceremony creates no Operators, no Accounts and no Policies. After the launch, the Master Administrators invite the other users from **Users**. See [**Users**](/help-center-v2/administration/users.md). ## Administrator names The Administrator name becomes the user name of the Master Administrator in the Workspace. * It has 1 to 19 characters, after the Onboarding app removes the spaces at the start and at the end. * It uses printable ASCII characters only. Letters with accents and other scripts are refused. * Each name is unique in the onboarding. * It cannot be changed later. The Onboarding app asks for a name with no personal information, such as "Admin 1". The app does not check this. ## Shared Owners A Shared Owner holds one of the three shards of the master seed of a hosted Workspace. A Workspace has exactly three Shared Owners. A Shared Owner is not a user of the Workspace. A Shared Owner does not sign in, and does not approve Requests. After the ceremony, the three Shared Owners are needed again only to recover the master seed. The recovery uses the 24-word recovery phrase of each Shared Owner device, not the device itself. See [**Recovering the master seed**](/help-center-v2/administration/onboarding/master-seed-recovery.md). A device cannot be both an Administrator device and a Shared Owner device in the same ceremony. ### Replacing a Shared Owner A Shared Owner can leave your organization, or die. Your organization keeps the role covered with its own process. Ledger does not run this process. A recommended set-up: * Keep each shard in its own bank safe. A shard here is the recovery phrase of one Shared Owner device. * Apply strict access controls to each safe. * Define a process that hands over the access to a safe to a new Shared Owner when the previous one leaves. > **Warning:** You may doubt the integrity of this process, or a shard may be lost or compromised. In either case, contact your Technical Account Manager (TAM) at Ledger at once for advice. ## The master seed The master seed is the root of the keys of every Account in a hosted Workspace. * The HSM generates it from three shards. Each Shared Owner device gives one shard. * It never leaves the HSM. No person and no device holds it. * To recover it outside the HSM, all three Shared Owner recovery phrases are necessary. ## What can go wrong | Message or state | What it means | What to do | | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- | --------------------------------------------------------------- | | This onboarding ID doesn’t exist. Please check your entry, or contact support. | No onboarding has this ID | Check the ID that Ledger gave you | | This onboarding ID cannot be reached at the moment. Please try again later or contact support. | The Onboarding app cannot load the onboarding | Try again later | | **Connect exactly one Ledger device** | More than one Ledger device is connected | Disconnect the other devices | | **An action is required**: open the Vault app | The Ledger Vault app is not open on the device | Open the Ledger Vault app, then claim again | | This device was already claimed and cannot be added a second time. | The device already has a role in this ceremony | Use a different device, or un-claim the first claim | | **Warning**, with **Cleanup registration** | A device registration did not complete | Select **Cleanup registration**, then register the device again | | An Administrator with same name or public key has already registered. Please check that you are using the right device & name. | The name or the device is already registered in this ceremony | Enter a different name, or connect the right device | | Administrator name must be 19 characters or fewer. | The name is too long | Enter a shorter name | | Administrator name can only contain printable ASCII characters. | The name has a character outside printable ASCII | Remove the character | ## Related * [**Recovering the master seed**](/help-center-v2/administration/onboarding/master-seed-recovery.md) * [**Your security device**](/help-center-v2/start-here/get-started/your-device.md) * [**Workspace settings**](/help-center-v2/administration/governance/workspace-settings.md) * [**Users**](/help-center-v2/administration/users.md) * [**The security model**](/help-center-v2/concepts/the-security-model.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://help.enterprise.ledger.com/help-center-v2/administration/onboarding.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.