Users
How a Master Administrator creates PSD and API users on Ledger Enterprise, issues API credentials, tracks registrations, and suspends or revokes access.
Role: Master Administrators.
Users lists everybody in the Workspace. It has two tabs: Users and PSD registrations.
The list carries each user's name, type, role, status, creation date and identifier. Search it by name, ID or device ID. Filter it by state, role or type.
The State filter offers Active and Revoked only. Suspended users appear under Active.
Operators can be organized into groups, which Rules use in place of individual names. See Groups.
The two user types
PSD is short for Personal Security Device: the credential that identifies a user and signs their approvals.
PSD user
Signs in and approves through the interface, on a Ledger device
A registration link, and the device's ID
API user
Works entirely through the API, signing with its own key
An externally generated public key
Both types take a role, Operator or Administrator.
In the interface, a name has at most 19 characters, in ASCII only. The API accepts up to 45 characters. Each name must be unique in the Workspace.
Important: Administrator creation is paused while a quorum change is in flight. Operator creation stays available. See Workspace settings.
Creating a PSD user
You need the invited person's device ID first: the 16-character identifier shown in the Ledger Vault app, in the form DEAD-BEEF-DEAD-BEEF. Ask them for it before you start.
Select Create user, then PSD user.
Enter the name and the device ID.
Select the role.
Create user.
The form rejects a device ID already used by an active user or an ongoing registration.
You then get a registration link. Send it to the invited user.
The invitation takes effect at once. It is not a Request. The user is created only when the activation Request is approved. See Tracking registrations.
Registering as an invited user
The invited user completes registration from the link, with their Ledger device. See Registering as a new user.
Tracking registrations
The PSD registrations tab follows an invitation from creation to activation.
Invitation created
The link exists. The user has not started registration
Pending registration
The user started registration and has not finished it
Pending admin activation
Registration is complete. A Master Administrator must select Activate
Pending admin approval
The activation Request is waiting for approval
From a registration you can select Copy registration link, Activate or Abort.
Activate is available only in Pending admin activation. It creates a Request to create the user, and Master Administrators approve it. While that Request is pending, Copy registration link and Abort are unavailable.
When the activation Request is approved, the registration leaves this tab. The user then appears in the Users tab.
When registrations are in Pending admin activation, Users in the navigation shows a red count of them. The PSD registrations tab shows the same count.
Aborting deletes the invitation. The copied link stops working, and the person cannot complete registration from it.
Creating an API user
Select Create user, then API user.
Enter the name.
Paste the public key. It must be an uncompressed secp256r1 key:
04followed by 128 hex characters.Select the role.
Select Review, and confirm on your device.
The form rejects a public key already used by an active user.
Creating an API user is a Request. Master Administrators approve it.
The approved Request does not issue an API key ID or secret. Until a Master Administrator issues them, the API user cannot authenticate. See Issuing the first API credentials. For how API users authenticate and approve, see API users.
Note: A new API Administrator has no permissions. It gets permissions only from the API admin rules in Workspace settings. A Master Administrator configures these Rules.
Issuing the first API credentials
A Master Administrator issues an API user's first API key ID and API key secret with Refresh credentials. Do this after the creation Request is approved.
In Users, find the API user. Its status is Active.
In the row menu, select Refresh credentials. The same button is also on the user's page.
In Refresh API credentials?, select Refresh.
Copy the API key ID and the API key secret.
Close the dialog.
Warning: The dialog clears the credentials when it closes. The platform does not show them again. If they are lost, refresh again. A refresh issues a new pair and stops the old pair immediately.
Issuing credentials is not a Request. It needs no approval and no Ledger device. The platform logs each refresh.
The user page
Select a user in the Users tab to open their page. To share it, select Copy link to user in the row menu.
The page shows:
Role, Status and Created. For a revoked user, it also shows Revoked, with the date.
Personal security device information. It gives the Type. For a PSD user, it gives the Identifier, which is the device ID, and the Model. For an API user, it gives the Public key, with a copy action.
History: the timeline of the Request that created the user.
Governance, for Operators only. Accounts lists the Accounts where the user takes part in a quorum, directly or through a group. Groups lists the user's groups, up to 8. In each part, View all opens the full list, filtered on this user.
The page header carries the actions available for the user: Refresh credentials for an API user, Revoke user permanently, and Suspend user or Restore access. Your own page shows no actions. The page of a suspended user shows the Temporary access lock banner.
Managing an existing user
Suspend
Blocks access immediately. Reversible. Not available for a PSD Administrator
Restore access
Lifts a suspension
Revoke
Ends access permanently
Refresh credentials
Issues a new API key ID and secret, for an active API user who is not suspended
Link portfolios
Adds an Operator to Portfolios, or removes it from them. See Portfolios
A user's status is Active, Suspended or Revoked.
Suspending
Access is blocked immediately. The user loses the platform, any pending Requests, and any Account information. You can restore it at any time.
You cannot suspend a PSD Administrator. To remove one, revoke them.
Revoking
Revocation is permanent and it is a Request, so it needs approval.
You cannot revoke yourself. You cannot revoke a Master Administrator if the Master Administrators left would no longer outnumber the quorum. While a revocation Request is pending, Revoke is unavailable for that user.
For most users, access is blocked immediately and the revocation is finalized when the Request is fully approved. In the interface, Revoke suspends the user first, then creates the revocation Request.
Important: An Administrator who is a PSD user keeps access while their revocation is being approved. They can still use the platform and see pending Requests. They cannot approve or reject their own revocation.
What a revocation removes
When the revocation Request is fully approved, the platform:
removes the user from every group and every Portfolio;
removes the user from every step of every Rule, including Request initiator steps and the API admin rules;
stops counting the user's approval at the current step of a pending Request. That step needs another approval.
The revocation Request also blocks Requests that the user created, or approved at an earlier step. This happens as soon as the revocation Request is created. See Blocked.
When the platform refuses a revocation
The platform refuses to create the revocation when a Rule step would have fewer members than its quorum without the user. The step can list users, or hold a group that the user is in. A user who is the only member of a step with a quorum of 1 is in this case. This applies in the interface and over the API.
To find the steps, open the user's page. For an Operator, Governance lists the Accounts and the groups where the user takes part.
To revoke the user:
In the Policy, the Account or the API admin rules that hold the step, lower the quorum or add a member.
For a step that holds a group, you can add a member to the group instead.
Wait until that Request is approved.
Revoke the user again.
In the interface, the suspension happens before the platform checks the steps. A refused revocation therefore leaves the user suspended. A PSD Administrator is the exception, because the interface does not suspend one. To lift the suspension, select Restore access.
The platform checks the steps again before it applies an approved revocation. If a change since the creation leaves a step too small, the revocation does not complete.
Refreshing API credentials
This issues a new API key ID and API key secret. It is also how an API user gets its first pair. See Issuing the first API credentials.
Warning: The existing credentials stop working immediately. The new secret is shown once, and is cleared when the dialog closes. Copy it before you close.
Related
Last updated