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 enr...

Written By Erdinc Akay

Last updated 25 days ago

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 installation token (also called an enrollment token) before they are accepted. This article is for administrators who want to control enrollment.

Before you start

You need an octoja account with the Agent Management permission, granted via groups under Administration → Groups. Without it, Agent Deployment and the Installation tokens page are not shown at all.
Requiring tokens is a deliberate switch to a more restrictive mode — once enabled, install commands without a valid token are rejected. Already-enrolled agents are not affected.

The two deployment modes

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

The Agent Deployment page in open-deployment mode: in Step 1 Settings the "Open Deployment" card is selected next to the "Token-based Deployment" card, and the "…" actions menu button sits at the top right of the page header.

Mode	Who can enroll	When to use
Open Deployment (default)	Any device with the correct server URL	Testing, small deployments, short setup phase
Token-based Deployment	Only devices with a valid installation token	Production, multi-tenant environments, compliance

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. To reject every tokenless enrollment, turn off open deployment (see "Require tokens for all new enrollments" below).

Use a token for a single rollout

Go to Administration → Agent Deployment.
In Step 1 – Settings, select the Token-based Deployment card. If no token exists yet, the Configure Deployment dialog opens.
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.

Require tokens for all new enrollments

Go to Administration → Agent Deployment.
Open the … menu at the top right of the page header and untick Allow open deployment (this switch is only shown to members of an administrator group). From now on, enrollment without a valid token is rejected. Already-enrolled agents keep running.

Step 1 – Settings now shows the token form inline — Deploy to customer (optional), Site (optional), and Token expires (optional). The "(optional)" suffix is part of each visible label; fill in any field you want to pin for new enrollments:

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

Click Create installation token. Tokens are never created automatically — until you create one, the later steps stay inactive and no install command is shown. Once the token exists, Token created appears next to the card title and Step 4 – Install shows the commands with the token embedded.

To issue another token later, adjust the fields and click Create new token. Editing the fields alone changes nothing — the token is only replaced when you create a new one.

The customer and site you pin here are inherited by every agent enrolled with the token. If a pre-assignment ever needs to change, the agent or asset has to be moved from its own page — the deployment pages do not re-assign already-enrolled agents.

View, create, and revoke tokens

Open the … menu on Agent Deployment and choose Manage tokens to open the Installation tokens page. It lists every token 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 Installation tokens page, reached via the "Manage tokens" entry in the Agent Deployment header menu. The "Create token" button in the page header is outlined in red; below it, the "Active" and "All tokens" filter tabs switch the token list.

Create a token: click Create token, optionally set Customer (optional), Site (optional), and Expiration date (optional), then confirm with Create token.
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 the … menu or the Installation 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 you created:

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 / GPO: the TOKEN="..." property appears in the rollout command.
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 — every Create action 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 Installation 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.

Switching back to open deployment

Open the … menu on Agent Deployment and tick Allow open deployment again. Existing tokens remain on the Installation 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.

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 Installation 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.