Collection tokens

A collect token authenticates data going into Sondar. Every agent, every OTLP exporter, every Splunk HEC shipper and every direct POST to the data API presents one. It is not a login and it grants no access to search, dashboards or settings — it only lets a sender write.

Manage them under Configure → Access Control → Collection Tokens.

There is a default token, and it is created for you

On first start, if collect tokens are enabled, Sondar creates one named default and leaves it enabled. The server uses it where an install names no other token. Its value is never displayed (see below), so to install by hand you need a token you created.

Two properties are worth knowing before you plan around it:

• Its value is unique to your instance. It is generated on your server at first start. It is not baked into the image and it is not shared between installs.
• It does not expire. Its expiry is stored as a sentinel that Sondar reads as never, and nothing rotates it on a schedule.

That is deliberate, and it matches how comparable products behave: Elastic Fleet creates an enrollment token automatically for every agent policy and treats an empty expiry as never expires, Datadog API keys have no built-in expiration, and Splunk HEC tokens do not rotate themselves.

Why it does not expire, and why that is not laziness

There is a real difference between Sondar’s collect token and an enrollment token.

When an Elastic Fleet enrollment token expires, agents that already enrolled keep working — it only stops new enrollments. Sondar’s collect token is not like that. It authenticates every ingest request, for the life of the sender. Expiring it does not inconvenience a future install; it stops the data from every machine already sending, at a moment nobody chose, some weeks after anyone thought about it.

So the token is long-lived on purpose. The protection you actually want is knowing it exists and being able to replace it — which is the rest of this page.

What a token looks like, and when you can see it

A token is collect_<id>.<secret>: the id is a random UUID and the secret is 256 random bits, in hex. The value is shown once, in the dialog that creates the token. Copy it then. The token list shows the id and no value; a token’s details show a masked value. Neither shows the secret, and the server will not show it again.

Install commands follow the same rule. A command generated for a token that has a secret names it as <collect-token>, and the install page says so under the command. Two ways to fill it in:

• Create a token for this install. The button under the command creates a token that never expires, named install-<date>-<time>, selects it in the Token field, and puts its value into every command on the page. On the Kubernetes tab, download deploy.yaml again and the file carries it. The value is shown only on that page: copy the command before you leave. You need permission to create collect tokens.
• Paste a token you already have: replace <collect-token> with the value you copied when you created it.

The SSH install is the exception: it runs the command on the host itself and shows you nothing, so it uses the full value.

The default token is created by the server, not in a dialog, so nobody sees its value. Installs that run on the server’s side (SSH installs, and the configuration the server sends to agents it manages) still use it. To install by hand, use the button above or create a named token — which is what the rest of this page recommends anyway.

Tokens created before October 2026 keep working. They have no secret: the value is collect_<id>, the id the list shows, and install commands still name it. Retire them as described under Rotating a token: the replacement has a secret.

Treat it as a credential

Anyone holding a collect token can write data into your instance. They cannot read anything, but they can fill a repo, distort a dashboard or trigger an alert rule.

• Do not paste it into a shared document, a ticket, or a chat channel.
• Do not commit it. Agent configuration files carry it in plain text, so those files are secrets too.
• Prefer one token per fleet or per environment over one token everywhere: a token you can retire without touching every machine is worth the small extra bookkeeping.

Rotating a token

Rotation is add-then-retire, never edit-in-place — a token’s value cannot be changed, and deleting one that senders are still using stops their data.

1. Create the replacement. Configure → Access Control → Collection Tokens → new token. Give it a name that says what it is for, not default2, and copy its value from the dialog: that is the only time it is shown.
2. Move senders onto it. Update the agent configuration or the exporter’s token: field and restart the sender. Do a few first and confirm their data is still arriving before moving the rest.
3. Confirm nothing is left on the old one. Watch the ingest volume attributed to the old token fall to zero. Give it longer than you think — a machine that is powered off at the moment you check is still configured with it.
4. Disable the old token, then delete it. Disabling is reversible and deleting is not, so disable first and leave it disabled for a while. If something breaks, re-enable and find out what you missed.

Retiring default

Nothing requires you to keep it. Once every sender is on a named token, disable default the same way. It will not be recreated while it still exists in any state.

If you disable collect tokens entirely in settings, the default is not created on the next start — but existing tokens are not removed, and senders keep using them.

What to check after an incident

If you believe a token has leaked, the order matters:

1. Create a replacement and move your senders, as above.
2. Delete the leaked token. Disabling is enough to stop it working; deleting removes it from the list so nobody re-enables it later.
3. Look at what arrived. A leaked collect token means somebody could have written data. Search the repos it could write to over the period it was exposed, and treat unexpected sourcetypes or hosts as suspect.