Configure Agent Enrollment Tokens

By default, any device that knows your octoja server URL can enroll an agent. For production environments, you can require new devices to present an enrollment token before they are accepted. This article is for administrators who want to control enrollment.

Before you start

• To select and manage rollout tokens, you need the Agent Management permission, granted via groups under Administration → Groups.
• To require tokens for every new enrollment under Settings → Agent enrollment policy, you must be a member of an administrator group.

The two deployment modes

In Step 1 – Settings on Administration → Agent Deployment, two cards let you choose how new agents enroll:

Selecting Token-based Deployment on this page only changes the install commands for the rollout you are preparing — devices without a token can still enroll as long as open deployment is allowed. This instance-wide policy is configured separately under Settings → Agent enrollment policy.

Use a token for a single rollout

1. Go to Administration → Agent Deployment.

2. In Step 1 – Settings, select the Token-based Deployment card. If no token is selected yet, the Configure Deployment dialog opens.

3. Optionally set Customer (optional), Site (optional), and Expiration date (optional), then click Save. octoja creates the token, and the install commands in Step 4 – Install include it automatically.

The Configure Deployment dialog offers two tabs. Create new is the path described above and is preselected while no token is in use. Switch to Use existing to reuse a token you already issued instead of minting another one: the Existing enrollment token field searches your tokens by customer, site, or expiration and lists each match with its customer, site, expiry date, and token value. Pick one and confirm with Use selected token.

Only tokens whose status is Active appear in that list — expired and revoked tokens are never offered. Selecting an existing token changes nothing about the token itself; it only decides which one the install commands in Step 4 – Install quote. Once a token is in use, the pencil icon next to it on the Token-based Deployment card reopens the dialog on Use existing with that token preselected.

Require tokens for all new enrollments

1. Open Settings → Agent enrollment policy.

2. Turn off Allow open deployment. From now on, enrollment without a valid token is rejected. Already-enrolled agents keep running.

3. Step 1 – Settings now shows the Token-based Deployment card on its own; with open deployment switched off there is no second mode to pick. Click Configure Deployment to open the same dialog as above, and on the Create new tab fill in any field you want to pin for new enrollments. The "(optional)" suffix is part of each visible label:

   Field	What it does
   Customer (optional)	Enrolled agents are automatically assigned to this customer. Leave it on Assign later if you don't want to pre-assign.
   Site (optional)	Pins agents to a specific site under the chosen customer (the field appears once you pick a customer).
   Expiration date (optional)	Expiry date — the token stops working for new enrollments after this date.

4. Click Save. Tokens are never created automatically — until one is in use, the later steps stay inactive and no install command is shown. Once a token is in use, the card shows its customer, site, expiry, and token value, and Step 4 – Install shows the commands with the token embedded.

To put a different token in use later, click the pencil Edit button on the card. The dialog reopens on Use existing with the current token preselected — choose another active token and confirm with Use selected token, or switch to Create new to issue a fresh one.

Selecting a different token on the deployment page does not move any devices by itself. The assignment takes effect when a device enrolls with that token, including re-enrollment after a reinstall. To change the assignment without reinstalling, use the device's page.

View, create, and revoke tokens

Open the … menu on Agent Deployment and choose Manage tokens to open the Enrollment tokens page. It lists the tokens you can reach, each with its scope (customer and site), creation and expiry dates, how often it has been used, and its status — Active, Expired, or Revoked. Switch the filter from Active to All tokens to include retired tokens.

The list follows your customer scope: if your groups cover only some customers, you see and manage the tokens for those customers. A token that applies to all customers is listed for accounts that can reach every customer.

• Create a token: click Create token, optionally set Customer (optional), Site (optional), and Expiration date (optional), then confirm with Create token.
• Reuse a token: click Use for deployment to jump back to Agent Deployment with that token already selected in Step 1 – Settings, so the commands in Step 4 – Install quote it right away. The action appears on Active tokens only.
• Revoke a token: click Revoke on the token and confirm with Revoke token. The token immediately stops working for new enrollments; devices that already enrolled with it are not affected. The token stays in the history as revoked.

Don't see the option? Tokens whose status is already Revoked show no Revoke action — they are kept as read-only history. If a token you expected is missing from the list, it belongs to a customer your groups do not cover. If the … menu or the Enrollment tokens page itself is missing, your account lacks the Agent Management permission — being an administrator does not grant it automatically. Add the permission to your group under Administration → Groups, or ask someone who manages groups to do it.

How the token reaches installers

Token mode does not change where administrators click or what technicians type. The install commands shown in Step 4 – Install automatically include the token in use:

• Windows (PowerShell): -Token 'YOUR-TOKEN' is appended.
• Windows (MSI): TOKEN="YOUR-TOKEN" is added to the msiexec command.
• Linux / macOS (shell): the token is passed as a second argument after the server URL.
• Intune: a TOKEN="..." line is added to the command-line arguments you paste into the app assignment.
• Group Policy (GPO): GPO software installation cannot pass MSI properties, so the token goes into a settings transform instead. Step 4 – Install offers a Download transform (.mst) button; attach the downloaded file on the GPO's Modifications tab. Download it again whenever the deployment moves to a different token.
• Sidecar file: if you use the installer.settings.json file instead of command-line arguments, it includes a "token" entry.

Technicians copy the command as usual — the token is already in it.

Multiple tokens and expiry

octoja does not enforce a single active token — creating one always issues an additional token, and all previously issued tokens stay valid until they expire or you revoke them. To retire a token, revoke it on the Enrollment tokens page, or give it an expiration date when you create it:

• Before the expiry date: the token works as normal (it stays valid through the selected day).
• After the expiry date: new installers that quote the token are rejected.

Reusing a token keeps that list short: the Use existing tab in the Configure Deployment dialog and the Use for deployment action on a token both pick up an already-issued token without creating one.

Switching back to open deployment

Open Settings → Agent enrollment policy and turn on Allow open deployment again. Existing tokens remain on the Enrollment tokens page and stay valid, but a token is no longer required — devices can enroll with the server URL alone.

Pre-assigning customer and site

Setting a customer (and optionally a site) on a token means every device enrolled with that token is automatically attached to them. Technicians do not need to remember to pick the right customer afterwards. This is especially useful for MSPs rolling out to a single tenant.

Assignment on re-enrollment

When an existing device enrolls again, these rules apply:

These rules also apply when re-enrollment restores a previously deleted device. An assignment to a deleted customer is not preserved; a token for a deleted customer does not assign the device back to that customer.

If the device is connected but you cannot see it, have its customer assignment and your groups' access checked. Unassigned devices are visible only to groups with global customer access and matching device access. See How Users, Groups & Permissions Work.

What the token does not do

• It is not a per-device secret. Every device installed with the same token shares it, and issuing a new token does not invalidate older ones — revoke tokens you no longer want on the Enrollment tokens page.
• It does not gate agents that have already enrolled — revoking or expiring a token has no effect on connected devices.
• It does not authenticate users — it only gates the initial enrollment handshake.

Related articles

• Step 3 – Deploy Your First Agent
• Deploy the Agent on Windows
• Deploy Agent on Linux
• Deploy the Agent on macOS