Enrolment tokens¶

An enrolment token lets people join your team by signing up with a string you give them, instead of an individual invite. Use it to onboard a whole office or fleet of machines. One team has one live token.

Anyone who holds the token can ask to join. What happens next depends on the guards you set: the email domain, admin approval, or both.

Creating a token¶

Open the vault's Share sheet, go to the Links tab and find Device enrolment. You need the permission to invite members.

Set at least one of the domains and the approval switch.

Domains match exactly on the part after the last @. acme.com does not admit eu.acme.com; list each one.

The token looks like vte1.<server>.<id>.<secret>. It identifies your server and team, but it doesn't contain any encryption key.

Self-hosted servers without email¶

If the server can't send email, it can't confirm that a person owns an address. Domain-only tokens are refused there, and the form turns An admin approves each join on and locks it.

Rotating and revoking¶

Creating a token again rotates it. The old token stops working for new joins at once, so update wherever you handed it out. Machines already enrolled with the old token keep getting the team's policy. Requests already waiting stay open and you can still decide them. Rotating keeps a future expiry.

Revoke removes the token without replacing it. Machines enrolled with it stop getting the team's policy. People who already joined stay members. Revoking works even if the team's plan has lapsed.

The section also shows when the token was last used and how many people are waiting or have joined through it.

Using a token¶

There are three ways to hand a token to people. With a token, sign-up works even when the server has sign-up closed. Each token allows up to 500 sign-ups a day, so rolling out from one office address is fine.

• Machines you manage. Run voltius-cli enroll on each one. See Enrol a fleet.
• A link. Next to the token, shown once after you create it, Copy link copies a link you can email or post. Opening it in Voltius starts the join. Anyone who has the link can ask to join, as with the token itself.
• The token itself. People paste it into Voltius. See What people see.

Enrol a fleet¶

Run voltius-cli enroll as root or Administrator on each machine. It writes the token into the machine policy as enrollment.token. The next time Voltius starts on that machine, it asks the person to sign in to your team.

sudo voltius-cli enroll "vte1.…"

By default the command asks your server to check the token first and prints the team name. Running it again with the same token changes nothing. See enroll in the command line reference for the options and exit codes.

With Ansible, --json reports whether the file changed:

- name: Enrol this machine in the company Voltius team
  ansible.builtin.command: voltius-cli enroll "{{ voltius_enrollment_token }}" --json
  become: true
  register: voltius_enroll
  changed_when: (voltius_enroll.stdout | from_json).changed

Keep voltius_enrollment_token in Ansible Vault or your secrets store. The token can't decrypt anything, but anyone who has it can ask to join.

When you build a machine image without network access, add --no-verify to write the token without asking the server. The server checks it when someone first uses it.

If the machine's policy locks server.url to a different server than the token's, the command refuses. Use the token from the locked server.

To enrol every machine and also lock your server, set both:

sudo voltius-cli policy set server.url https://voltius.acme.com
sudo voltius-cli enroll "vte1.…"

Rotating or revoking the token doesn't remove it from machines. Run voltius-cli enroll with the new token, or voltius-cli enroll --remove.

Team policy on enrolled machines¶

On a machine whose machine policy has enrollment.token, the team's policy applies to every account on that machine: signed out, offline accounts, personal accounts and accounts on other servers. People can't drop the team's locks by switching accounts.

• Voltius fetches the policy from your server with the token, when it starts and about every 15 minutes while it is open. Changes you save in Members → Security → Device policy reach enrolled machines within 15 minutes.
• It keeps applying offline, from the last policy it received.
• The enrolling team ranks first if a person's own teams set the same key.
• Rotating the token keeps machines enrolled with the old one managed. Revoking it stops their team policy. An expired token only stops new joins; machines keep getting the policy.
• The policy keeps applying if the team's plan lapses.

To stop managing a machine, remove enrollment.token from it with voltius-cli enroll --remove, or remove it from the MDM configuration. A token pasted in the app or opened from a link only joins that person; it doesn't put the machine under the team's policy.

What people see¶

First launch. On a machine with a token, a new person sees Sign in to instead of the generic welcome screen. The server is your organization's and can't be changed here. They create an account or sign in with their email, and the join request is sent. If the token has domains, the form says which email to use. Skip for now is always there.

A link. Opening the link shows the team and the server, and asks first: Only continue if your company sent you this link. Nothing is sent until they continue. Then they get the same form. People who are already signed in to that server can join with the account they have, or use another one.

A pasted token. On the first-launch screen, Have an enrolment token? opens a field for it. The same confirm step appears. Tokens written by voltius-cli enroll don't ask, because an administrator of the machine put them there.

If a person skipped, or you enrol a machine later, a notification says Your organization uses on Voltius, with Sign in.

After they submit, the screen says what happens next:

The same status stays in their notifications until it resolves: waiting for approval, verify your email, or You joined once an admin approves. If an admin denies the request, the notification says the team declined it. On a machine with a token, Ask again sends a new request.

How people are admitted¶

• Domain rule only. A person is admitted automatically when their email matches a listed domain and they have confirmed it by clicking the link in the verification email.
• Admin approval. The person waits in the join requests list until an admin decides.
• Both. The email must match a listed domain, and an admin must still approve.

A seat is used only when someone is admitted, not while they wait.

Accounts verified before this release, and accounts on servers that verify automatically, have to confirm their email again. They use Resend email in the "Verify your email" notice, which is limited to 5 per hour.

A person without an encryption key can't join. They need to sign in to the Voltius app once first.

Join requests¶

Open Members → Join requests to see who is waiting. Admins with the invite-members permission see it. Each request shows why it is waiting:

• Waiting for approval
• Waiting for email verification: they admit themselves once they confirm.
• No seat left: add seats in Billing, then approve.

Click Approve to admit the person with the token's role, or Deny to refuse. A denied person can ask again with the token.

If the plan lapses¶

While the team's plan is below Business, the token can't be resolved or redeemed and requests can't be approved. You can still deny requests and revoke the token.

See also Members and Roles & permissions.